Why Android app links fail
App links open in browser, not app
If links open Chrome instead of your app, the assetlinks.json file is not validating or SHA-256 does not match. Without autoVerify, users see app chooser dialog.
Android app links require three critical components: correct SHA-256 fingerprint, proper assetlinks.json hosting, and autoVerify enabled. A single mismatch breaks the entire system.
SHA-256 Fingerprint
Must match exactly from your signing key. Use Play Console version if using Play App Signing.
assetlinks.json
Must be valid JSON, properly hosted at .well-known/, and accessible to Google servers.
autoVerify
Intent filter attribute that enables automatic verification when app installs.
Step-by-step troubleshooting
Get your correct SHA-256 fingerprint
Critical: Use the fingerprint from Google Play Console, not your local keystore.
- If using Play App Signing: Go to Google Play Console > App signing for internal testing
- Copy the SHA-256 certificate fingerprint shown in the console
- If self-signing: Run keytool -list -v -keystore keystore.jks | grep SHA256
- Format must be pairs separated by colons: AA:BB:CC:DD... (no spaces)
- Save this value to use in assetlinks.json
Create and validate assetlinks.json
Your JSON must be valid and include the correct SHA-256 fingerprint.
- Create file .well-known/assetlinks.json in your web server root
- Use format: [{"relation":["delegate_permission/common.handle_all_urls"],"target":{"namespace":"android_app","package_name":"com.example.app","sha256_cert_fingerprints":["AA:BB:CC:..."]}}]
- Validate with /assetlinks-validator before deploying
- Check for trailing commas, missing quotes, or other JSON syntax errors
- Test in browser: domain.com/.well-known/assetlinks.json should return JSON
Add autoVerify to intent filter
This attribute enables automatic verification when your app installs.
- Open your AndroidManifest.xml
- Find the intent-filter for deep links
- Add: android:autoVerify="true" to the intent-filter tag
- Example: <intent-filter android:autoVerify="true">
- Rebuild and test your app after making this change
Verify hosting and accessibility
Google and Android must be able to fetch your assetlinks.json without restrictions.
- Test file is accessible: curl -I https://yourdomain.com/.well-known/assetlinks.json
- Should return 200 OK with Content-Type: application/json
- Verify no authentication, IP restrictions, or WAF blocks Google servers
- Check for redirect chains (Google can follow up to 5 redirects)
- Ensure DNS resolves correctly and certificate is valid
Verify in Google Play Console
Google Play Console shows verification status and issues.
- Go to App Links section in Google Play Console
- Check "Digital Asset Links" verification status
- If verification fails, follow error messages to identify issues
- Common errors: wrong SHA-256, assetlinks.json not found, invalid format
- After fixing, re-test verification (may take up to 2 hours)
Common causes of app link failures
Wrong SHA-256 fingerprint
Cause: Using local keystore fingerprint when Play App Signing is enabled
Fix: Get SHA-256 from Google Play Console > App signing, not keytool output
assetlinks.json not found (404)
Cause: File is not at .well-known/assetlinks.json or web server not configured
Fix: Verify file location and test with curl. Ensure web server serves from correct root.
Invalid JSON in assetlinks.json
Cause: Syntax errors like trailing commas, missing quotes, or formatting issues
Fix: Use /assetlinks-validator to identify JSON errors before deploying
Wrong content-type header
Cause: assetlinks.json served as text/plain instead of application/json
Fix: Configure web server (nginx, Apache, CDN) to serve with application/json
autoVerify not in intent-filter
Cause: Attribute missing from AndroidManifest.xml
Fix: Add android:autoVerify="true" to your deep link intent-filter
assetlinks.json changes not deployed
Cause: CDN caching or web server not updated with new file
Fix: Purge CDN cache and verify new file is live before testing
Package name mismatch
Cause: assetlinks.json contains different package name than your app
Fix: Verify package_name in assetlinks.json exactly matches AndroidManifest.xml
Fingerprint has spaces or lowercase
Cause: Formatting issues in SHA-256 value
Fix: Ensure uppercase hex with colons between pairs: AA:BB:CC:DD (no spaces)
Android app links fix checklist
Debug Android app links with Redirectly
Use Redirectly's free assetlinks.json validator to test your configuration and identify issues:
Frequently asked questions
What is the difference between Play App Signing and local keystore?
Google Play Console can re-sign your app with a different key (Play App Signing). This creates a different SHA-256 fingerprint than your local key. Always use Play Console fingerprint for production verification.
Can I test app links before uploading to Play Store?
Yes. Test locally with your local keystore SHA-256, or use Play Console's internal testing track which shows the actual Play App Signing fingerprint.
How long does app link verification take?
Android verifies assetlinks.json when the app installs. If verification fails, users see app chooser dialog instead of automatic open. Fixing and reinstalling should work immediately.
Can I have app links for multiple domains?
Yes. Create assetlinks.json on each domain, and add multiple data entries in your AndroidManifest.xml intent-filter. Each domain needs its own assetlinks.json file.
What if my app uses App Links but users still see chooser dialog?
autoVerify may be missing, or app is not installed with correct signing key. Check Android System Settings > Apps > Your App > Supported Links for verification status.