Deep linking · Research note
Broken App Links: A Diagnostic Taxonomy
When an app link fails and none of the designed browser cases apply, the fault sits in one of six layers: the file host, the signing keys, the Android manifest, the Apple entitlement and file format, caching, or a retired service. Each layer has a symptom and a check.
Scope and limits
Faults and checks are taken from Android's and Apple's troubleshooting documentation and Firebase's deprecation FAQ. We have not counted how often each fault occurs.
The taxonomy
| Layer | Fault | Symptom | Check |
|---|---|---|---|
| File host | Redirect on the file (http to https, bare domain to www) | No App Links verify for the app | Request the file and confirm a direct 200 response |
| File host | AASA blocked (403, 404) or filtered by user agent | Universal links never open the app | swcutil dl -d; review bot and geo rules for /.well-known/ |
| File host | Missing file on a subdomain | Links work on one host only | Request the file on every host and subdomain |
| Signing | Fingerprint not matching the signing certificate | Android host not verified | Compare with the Play Console and your keystore |
| Signing | Upload key listed, Play signing key missing | Verified in testing, not for store installs | List the key Google uses to sign releases |
| Signing | Lower-case fingerprint | Android host not verified | Rewrite in upper case |
| Manifest | No autoVerify on any web intent filter | No verification runs | Add autoVerify to at least one filter |
| Manifest | Unowned or non-verifiable host in a filter | On Android 11 and lower, all hosts fail | Remove hosts you cannot serve a file on |
| Manifest | Non-verifiable test hosts in the release manifest | On Android 11 and lower, verification of all hosts is skipped | Keep test hosts out of release manifests |
| Apple | Mixed appIDs/components and appID/paths formats | Unpredictable matching | Use one format |
| Apple | Port number in an applinks domain | Domain not associated | Remove the port |
| Caching | File changed recently | Old behavior persists | Wait for Apple's CDN and device checks; on Android 15 and later, up to seven days |
| Dynamic rules | Malformed or empty rule | All dynamic rules ignored | Check the shape; Android falls back to the manifest |
| Retired service | Old Firebase Dynamic Link | HTTP 404 for visitors | Replace with your own verified https link |
Server faults come first
Android's troubleshooting guide is blunt about redirects: "The system doesn't verify any Android App Links for your app if you set up a redirect" such as http://example.com to https://example.com, or example.com to www.example.com. Apple's note says redirects are not supported for the association file either, and that a 403 or 404 means access is denied. On gambling sites, location blocks and bot protection are the first things to rule out for /.well-known/. The guide also asks you to check that example.com., with a trailing period, serves the same content as example.com.
Signing faults
Android's guide lists four: a signature that does not match the one used to sign the app, a debug-signed build checked against a release-only file, a lower-case signature, and a missing Play App Signing key: "If you are using Play App Signing, make sure you're using the signature that Google uses to sign each of your releases." The association file linter catches format slips such as lower case or a missing pair; only your keystore and the Play Console can confirm the values.
Manifest and entitlement faults
On Android 11 and lower, one bad host can sink them all: the app becomes the default handler only if a matching file exists for every host, and non-verifiable links "cause the system to not verify all Android App Links." On Apple platforms, check that the Associated Domains capability lists an applinks: entry for each domain, without ports, and that the file uses one format, either appIDs and components or the older appID and paths. A link that redirects through another host can be broken down in the route inspector.
Time-based faults
Some faults are only delays. Apple's network requests the file within 24 hours and devices check about weekly; Android 15 and later can take up to seven days; Android 14 and lower do not re-verify on a schedule. Firebase Dynamic Links are a different case: after the August 25, 2025 shutdown, clicked links return HTTP 404 for good. The migration guide covers the replacement.
Before you blame configuration, rule out designed behavior with the note on links that open the browser, then run the device test plan for deep links on a clean device.
Questions
Why did Android reject every host when only one was wrong?
On Android 11 and lower, the app becomes the default handler only if Android finds a matching file for all hosts in the manifest, and non-verifiable links make it skip verification for all App Links. Remove or fix the odd host.
Our corrected AASA file is live but devices ignore it. Why?
Devices get the file from Apple's network, which requests it within 24 hours, and check for updates about once a week. Use developer mode to test the new file directly while the public copy catches up.
Why does the Play Console show a different fingerprint from our keystore?
With Play App Signing, Google signs the releases people install, so assetlinks.json needs the fingerprint of Google's signing key. The troubleshooting guide asks you to use the signature Google uses for each release.
Sources
- Android Developers, Troubleshoot App Links, last updated October 23, 2026.
- Android Developers, Verify App Links, last updated October 23, 2026.
- Android Developers, Configure website associations and dynamic rules, last updated October 23, 2026.
- Apple Developer, TN3155: Debugging universal links, latest revision May 15, 2025.
- Apple Developer, Supporting associated domains, no date shown.
- Firebase, Dynamic Links Deprecation FAQ, last updated October 22, 2026.
How we choose and date sources: data sources.