Why universal links fail on iOS
Universal links fall back to web browser
If your universal links open in Safari instead of your app, the AASA file is not validating or the app is not installed. This is Apple's fallback behavior.
iOS universal links require a perfect configuration of three components: the AASA file, app entitlements, and domain validation. If any one is wrong, the entire system fails silently.
AASA File
Apple-app-site-association must be valid JSON, properly hosted, and correctly formatted with your app details.
Entitlements
Your Xcode project must have Associated Domains capability enabled with proper domain configuration.
Domain Validation
Apple must be able to fetch and validate your AASA file before the app can open universal links.
Step-by-step troubleshooting
Validate your AASA file
Use our free AASA validator to check for JSON errors, content-type issues, and configuration problems.
- Copy your AASA file content into the validator at /aasa-validator
- Check that JSON is valid and properly formatted
- Verify content-type is application/json (not text/plain)
- Ensure applinks key is present with correct bundle ID and team ID
Check your Xcode entitlements
Associated Domains capability must be enabled and properly configured in your signing settings.
- Open Xcode > Select target > Signing & Capabilities
- Click + Capability and add Associated Domains
- Enter domain(s) in format: applinks:yourdomain.com
- For subdomains, use: applinks:*.yourdomain.com
- Rebuild and resign your app with updated entitlements
Test on a real iOS device
The iOS Simulator does not validate AASA files or entitlements. Testing on Simulator masks real issues.
- Build and deploy your app to a physical iPhone or iPad
- Delete the app completely from the device (long press > Remove App > Delete App)
- Wait 1-2 minutes for AASA cache to clear
- Reinstall the app from Xcode or TestFlight
- Test the universal link on the real device
Verify AASA file is accessible
Apple must be able to fetch your AASA file without redirects or authentication barriers.
- Test in browser: https://yourdomain.com/.well-known/apple-app-site-association
- Should return JSON, not 404, 403, or redirect
- Check CDN headers: Content-Type should be application/json
- Verify no authentication or IP restrictions block Apple servers
- If using redirects, keep to 5 redirects maximum
Check for CDN caching issues
CDN caching can prevent AASA updates from being deployed. Some CDNs require explicit cache purging.
- Check CDN cache settings for /.well-known/apple-app-site-association
- Set cache-control headers to low TTL during development (e.g., 300 seconds)
- Purge CDN cache after AASA file updates
- Consider hosting AASA directly on origin (no cache) while debugging
- Verify Cloudflare, Fastly, or other CDN is not caching the file
Common causes of universal link failures
AASA file not valid JSON
Cause: Syntax errors, trailing commas, or missing quotes in apple-app-site-association
Fix: Use the AASA validator to identify JSON errors and correct syntax
Wrong content-type header
Cause: AASA served as text/plain instead of application/json
Fix: Configure your web server or CDN to serve with Content-Type: application/json
Team ID or bundle ID mismatch
Cause: Values in AASA file do not match your app entitlements exactly
Fix: Verify team ID from Apple Developer Portal and bundle ID from Xcode
Associated Domains not enabled in Xcode
Cause: Capability not added to app signing settings
Fix: Add Associated Domains capability in Xcode > Signing & Capabilities
Testing on iOS Simulator
Cause: Simulator does not validate AASA or entitlements
Fix: Always test on a real device during development and troubleshooting
Aggressive CDN caching
Cause: CDN caching the AASA file, preventing updates from being deployed
Fix: Purge cache after AASA updates or set low TTL during testing
Too many redirects
Cause: AASA file requires more than 5 redirects to reach final destination
Fix: Host AASA directly at /.well-known/apple-app-site-association or minimize redirects
Subdomain configuration
Cause: Wildcard patterns or specific subdomains not matching links
Fix: Use applinks:*.domain.com for all subdomains or specific subdomains individually
Universal links fix checklist
Debug universal links with Redirectly
Use Redirectly's free AASA validator to test your configuration and get detailed error messages:
Frequently asked questions
Why do universal links work in Simulator but not on device?
Simulator never validates AASA files or entitlements. Always test on real hardware. Simulator testing provides a false sense of success.
How long does it take for AASA changes to take effect?
Apple caches AASA for up to 24 hours. Delete and reinstall the app to refresh the cache immediately. For real devices, you can also force refresh by deleting app and reinstalling.
What if my app opens the link but in the wrong view?
This means universal links are working, but your app is not handling the deep link data correctly. Check your AppDelegate or SwiftUI scene handling for the Userinfo payload.
Can I use universal links with multiple domains?
Yes. Add multiple domains to Associated Domains (applinks:domain1.com, applinks:domain2.com) and create an AASA file for each domain.
Do I need both AASA file and custom URL scheme?
No. Universal links are better. URL schemes are fallbacks. Use universal links for all modern iOS apps. URL schemes only if you support iOS 8 or earlier.