# Universal Links Not Working? Fix iOS Deep Links

> Fix iOS universal links with this troubleshooting guide. Debug AASA file issues, entitlements, Associated Domains, CDN caching, and simulator limits.

- Canonical: https://redirectly.app/debug/universal-links-not-working
- Site: [Redirectly](https://redirectly.app) — deferred deep linking for Flutter & React Native

Comprehensive troubleshooting guide to debug and fix iOS universal links issues. Learn about AASA file validation, Associated Domains configuration, CDN caching, and testing strategies.

## 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

### 1. 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

### 2. 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

### 3. 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

### 4. 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

### 5. 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

- AASA file is valid JSON (validate with /aasa-validator)
- Content-Type header is application/json
- AASA file is accessible at /.well-known/apple-app-site-association
- Team ID in AASA matches Apple Developer Portal account
- Bundle ID in AASA matches Xcode project exactly
- Associated Domains capability is enabled in Xcode
- Associated Domains entries are in format `applinks:domain.com`
- App is signed with correct provisioning profile
- Testing on real iOS device (not Simulator)
- App has been completely deleted and reinstalled after changes
- CDN cache has been purged after AASA updates
- No redirect chains exceed 5 hops
- No authentication or IP restrictions block Apple servers
- Tested on at least iOS 14+ (universal links support)

## Debug universal links with Redirectly

Use Redirectly's free AASA validator to test your configuration and get detailed error messages:

- [Test your AASA file](https://redirectly.app/aasa-validator.md)
- [Flutter Deep Linking Guide](https://redirectly.app/flutter-deferred-deep-linking.md)

## 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.

---

Full site index for AI agents: https://redirectly.app/llms.txt