Universal links troubleshooting: what to check before you blame the app
Universal links and Android App Links usually fail for a small set of infrastructure reasons. If your link opens the browser instead of the app, start with the association files, not the UI.
Start with the file response, not the app
When universal links fail, teams often jump straight into app configuration. In practice, the faster path is to confirm that your Apple AASA and Android assetlinks.json files are being served correctly. If the files are wrong, app-side changes will not fix the problem.
What fails most often
- Association files redirect instead of returning directly.
- Responses use the wrong content type.
- JSON is malformed or incomplete.
- Files are deployed to the wrong path.
- Changes are rolled out without re-validating the domain.
The universal links troubleshooting checklist
1. Confirm the file path
- Make sure AASA and assetlinks.json are available from the expected location.
- If the path is wrong, platform verification can fail even if the content itself is valid.
- Check the exact production domain, not just a staging or test host.
2. Remove unnecessary redirects
- Association files should be served directly when possible.
- Redirect chains are a common cause of silent verification failures.
- Re-test after CDN, proxy, or domain changes.
3. Verify the content type
- A correct JSON payload can still fail if the response headers are wrong.
- Check the effective content type returned by the live endpoint.
- Validate the response from the real public host, not only from local tools.
4. Check the JSON body
- Look for malformed JSON, missing brackets, or invalid keys.
- Review the payload after any manual edits or deployment automation changes.
- Keep files as small and focused as possible to reduce rollout risk.
How the LinkMe validator actually evaluates your domain
The Universal Links Validator in LinkMe is not a generic linter. It calls the LinkMe API route and runs concrete checks used by the platform service. That means the output maps directly to real deployment behavior, not abstract recommendations.
| Check area | What LinkMe checks | Why it matters |
|---|---|---|
| Endpoint target | Normalizes the host and checks both /.well-known/apple-app-site-association and /.well-known/assetlinks.json. | You validate the same endpoints iOS and Android rely on during association verification. |
| Redirect handling | Fetches with manual redirect handling and flags redirects as errors for both files. | Association files should be served directly. Redirects can break verification. |
| HTTP status | Requires 200 responses; unexpected statuses are treated as failures. | Non-200 responses usually mean your app association cannot be trusted by the platform. |
| Content type | Warns when content type is incorrect (AASA expects JSON or signed pkcs7, assetlinks expects JSON). | Correct content type is required for predictable parsing and verification. |
| Payload structure | Validates AASA applinks.details structure and assetlinks relation/target keys. | Syntactically valid JSON can still fail if expected keys are missing. |
| File size safety | Reads with a 200KB ceiling and warns when files exceed expected size. | Oversized files increase verification and rollout risk. |
If you want to inspect implementation details, see the server-side checks in the LinkMe codebase:apps/edge/src/services/universalLinksService.ts andapps/edge/src/routes/tools.ts.
Symptom-to-fix matrix
| Symptom | Likely cause | Fix order |
|---|---|---|
| Link opens web instead of app | Association file path, redirects, or headers are wrong. | Fix endpoint path -> remove redirects -> verify content type -> re-validate JSON. |
| Validator returns status error | Domain, proxy, CDN, or hosting path mismatch. | Confirm production host and response path, then re-run validation. |
| JSON parse error | Malformed payload or invalid edits in deployment pipeline. | Repair JSON first, then re-check structure and required keys. |
| AASA warning but no hard error | Content type or size is outside ideal range. | Address warnings before launch even when basic parsing succeeds. |
| Intermittent post-release failures | Infrastructure changes shipped without re-validation. | Re-run validator after DNS/CDN/cert changes and before campaign cutover. |
AASA-specific checks
- Confirm the Apple App Site Association file is reachable from the live domain you intend to use.
- Check whether the Apple CDN cached copy reflects your latest deployment yet.
- Re-run validation after certificate, CDN, or reverse-proxy changes.
- Use the validator again after updating path rules or app association settings.
assetlinks.json-specific checks
- Verify the assetlinks.json file is served from the correct public path.
- Make sure the response returns directly and does not redirect through a marketing or CDN layer.
- Validate the JSON structure before reviewing package or signing details.
- Re-test after app release changes that affect package or certificate metadata.
Pre-launch QA sequence for marketing and engineering
- Deploy association files to the exact production host used by campaign links.
- Run the validator and clear red errors first (status, redirects, parse failures).
- Resolve warnings next (content type, file size, suspicious payload shape).
- Test a real link open flow on iOS and Android devices.
- Verify fallback behavior for users who do not have the app installed.
- Only then approve campaign distribution (email, ads, QR, creator links).
If your flow includes install-time context recovery, pair this checklist with the Deferred Deep Linking Guide so routing validation and deferred claim behavior are tested together.
A practical rollout flow
- Deploy the association files to the production domain.
- Run the Universal Links Validator and clear all obvious errors first.
- Re-check after any proxy, domain, or certificate change.
- Only then move to app-side QA and campaign testing.
- Repeat validation before major launches or domain migrations.
Helpful next steps
- Universal Links Validator - check AASA and assetlinks.json before launch.
- Custom domain setup - review domain configuration when hosts change.
- Smart links overview - understand how fallbacks and routing fit together.
Fix the infrastructure issues first
Most universal link failures are fixable without a full app release. Validate the files, remove response issues, and re-test before changing the app code or blaming the platform.
Universal links troubleshooting FAQ
Why do universal links open the browser instead of the app?
The most common causes are AASA or assetlinks.json files being unreachable, redirecting unexpectedly, returning the wrong content type, or containing invalid JSON. You should verify the file path, the response headers, and the payload before debugging app-side behavior.
What should I check first when App Links fail on Android?
Start with the assetlinks.json file path, confirm the response does not redirect, verify the content type, and make sure the JSON is valid. If the file is technically reachable but still fails, review the package and signing data you published.
Can I test AASA and assetlinks.json before launch?
Yes. Run the Universal Links Validator before shipping, then re-run it after any infrastructure or domain change. It helps you catch redirect issues, content-type mistakes, JSON problems, and file-size limits before they affect production traffic.