Universal links not opening app on iOS — fix

iOS universal links open the corresponding native app when the app is installed and the system has validated the association. When a link opens Safari instead — or opens the app inconsistently — one of seven conditions is usually the cause. Run them in order.

Fix steps

1. Confirm the AASA file is reachable. Visit https://yourdomain.com/.well-known/apple-app-site-association in a browser. The file must return HTTP 200, content-type application/json, served over HTTPS, with no redirects. Even a 301 to the same path breaks association.

2. Validate the AASA payload. The JSON must list your appID (Team ID prefix + bundle ID) under applinks.details. Run the file through a JSON linter. iOS rejects AASA files with a single comma error silently.

3. Verify the app is installed and was installed from the App Store or a signed build. Universal links do not associate for apps installed via TestFlight on some iOS versions. Test on a production-signed build.

4. Check the link origin. Universal links only fire when the user taps a link from another app — Mail, Messages, Notes, another browser. Links typed directly into Safari's address bar always open in Safari. This is intentional iOS behavior.

5. Check the webview context. Universal links do not fire inside in-app browsers (Instagram, TikTok, Threads, Messenger). The webview opens the link itself rather than handing off to the app. This is the most common cause of "the link works from iMessage but not from Instagram."

6. Trigger AASA re-fetch on the device. iOS caches AASA aggressively. Delete the app, restart the device, reinstall from the App Store, and tap the universal link again. This forces a fresh association check.

7. Confirm the applinks entitlement is present in the app's .entitlements file and matches the domain in AASA. A mismatch silently fails.

If all seven pass and the link still opens Safari from a known-good origin (iMessage), open a Console session in Xcode while tapping the link to see the system's association decision.

Still not working?

If the link fires correctly from iMessage but never from Instagram, TikTok, or Threads, you are hitting the in-app webview limitation, which is not fixable with AASA alone. A redirect layer that detects the webview and force-bounces to Safari is required.

Want the full diagnosis? See universal links and the AASA file explained.

Related help

• App Links not opening Android
• Branch link goes to App Store every time
• PDF not opening from Instagram

Need a redirect layer that opens your app from inside Instagram and TikTok? Start free on linkboo →