Why are my universal links / app links not working?
Mobile deep links only work when your domain serves two small public files correctly. When they break, links silently fall back to opening the mobile browser instead of your app. The usual culprits:
- The file isn't found — no
apple-app-site-association at /.well-known/, or no assetlinks.json there. - It redirects — apex ↔
www redirects are the classic trap. Apple and Google read these files without following redirects, so the file must be served directly. - Android fingerprint mismatch — the SHA-256 signing fingerprint in
assetlinks.json went stale after a key rotation or Play App Signing migration. - Wrong app ID / package — your
TeamID.BundleID or package name isn't listed in the file. - Malformed JSON or wrong Content-Type on the served file.
What this tool checks
Deep Link Doctor fetches your domain's apple-app-site-association (AASA) and assetlinks.json exactly the way Apple and Google do, then validates the HTTP response, the JSON structure, your app IDs, and — for Android — that the SHA-256 fingerprint still matches. It works on public, domain-side data only; it never needs your app binary.
Frequently asked questions
Why are my iOS Universal Links not working?
The most common causes are a missing apple-app-site-association (AASA) file, the file being served via a redirect (Apple does not follow redirects), the wrong Content-Type, invalid JSON, or your app ID not being listed in the file.
Why is my Android App Link not verified?
Usually the assetlinks.json file is missing at /.well-known/assetlinks.json, the package name does not match, or — most commonly — the SHA-256 signing fingerprint changed (for example after migrating to Play App Signing or rotating your key) and no longer matches the one in the file.
Where do these association files have to live?
iOS reads https://yourdomain/.well-known/apple-app-site-association (with a legacy fallback at the domain root). Android reads https://yourdomain/.well-known/assetlinks.json. Both must return HTTP 200 with no redirect.
Does Deep Link Doctor need my app's source code or binary?
No. It only reads the public association files your domain serves. It never needs your app, your account, or any private data.