Universal Links Not Working: 9 Causes and How to Fix Each

Universal Links not working means a link on a domain your app claims opens in the browser instead of the app, which Apple's TN3155 Debugging universal links, revised 15 May 2025, traces either to the server that hosts the apple-app-site-association (AASA) file or to the app itself.

The main benefit of finding the cause first is that nothing gets changed blindly: four tests on a device and a Mac tell which of nine causes it is before any file or code is touched. The causes run from the server, through the file and the entitlement, to the place the link was tapped and the app's own handler. Each fix is short, and each one is tested the same way. Timing matters more than most guides say: on iOS 14 and later the device reads the file from Apple's content delivery network (CDN), and devices check for updates about once a week, so a fixed file can take up to a week to reach a device that already has the app (Apple Developer, TN3155).

This page gives the tests first, then the nine causes in order, each with how it shows and how to fix it, then how to confirm the fix on a real device. A cause on the server, in the file or in the entitlement, causes 1 to 4, shows on every device; when universal links open Safari on one device only, start with causes 5 and 8.

You find why a Universal Link opens Safari by running four tests, each of which separates some causes from the rest:

  1. Long-press the link in Notes: when both the app and the browser are offered, the setup works and the cause is where the link was tapped or the app itself (causes 6 to 9); when only the browser is offered, the cause is on the server, in the file or in the entitlement.

  2. Run Diagnostics: turn on Developer Mode, then in Settings, Developer, Universal Links, turn on Associated Domains Development, open Diagnostics and type the full URL; TN3155 says it gives "feedback on whether this link is valid for an installed app."

  3. Request the file with curl -v https://example.com/.well-known/apple-app-site-association: a 301, 302, 403 or 404 points to cause 1, and a body that isn't the JSON you expect points to cause 2.

  4. Run sudo swcutil verify -d example.com -j ./aasa.json -u https://example.com/path on a Mac: "matched" clears the patterns, and "blocked match" or no match points to cause 4.

Smler's free deep link tester runs the file checks and the path match for a domain and a URL with no account, and the deep link troubleshooting guide covers the deferred link cases that sit beside these.

1. Is the AASA file unreachable or redirected?

Unreachable means Apple's CDN can't fetch the file at its exact address, and the curl -v test shows it as a redirect, an error or a certificate failure. TN3155 says a 301 or 302 on the path is an HTTP redirect that "is not supported", and a 403 or 404 means the site "denied access", usually because the path is blocked by IP address, region, a login or the user agent. Serve the file directly at https://domain/.well-known/apple-app-site-association on every domain in the entitlement, with a valid certificate. Allow it from every IP address and user agent, and test with a random one, as TN3155 shows:

Code
curl -A "MyAgent-Bot/*" https://example.com/.well-known/apple-app-site-association

2. Does the AASA file use the wrong format?

Wrong format means the file is reachable but iOS can't read an app and its patterns from it: the JSON is invalid, applinks or details is missing, the legacy appID and paths keys are mixed with "appIDs" and "components", or the app ID isn't the signed app's. TN3155 asks: "Please avoid mixing formats." Apple's QA1916 adds that the correct app ID "is the same as the application-identifier entitlement in your exported app archive", which can differ after an app was transferred between developer accounts. Use one format, the current "appIDs" and "components" one, and copy the app ID from the exported archive.

3. Does the entitlement miss the domain?

Missing domain means the applinks: entry names a domain that has no file of its own, so iOS never finds an association for it. TN3155 says a file on example.com serves applinks:example.com and applinks:*.example.com, but not applinks:www.example.com, and that "Each specific subdomain in your applinks should have its own matching AASA file path." A port number never works: applinks:example.com:8080 "will not open your app." Add one entry and one file for each subdomain, with the domain written with no path, query or trailing slash.

Outside the components means the file and the entitlement are right, but no "/" pattern matches the link's path, an "exclude" rule earlier in the list blocks it, or a "?" or "#" rule fails on its query or fragment. The swcutil verify -u test shows it: TN3155's example prints Pattern "https://example.com/test" matched. for a match and blocked match for an excluded path. Test the exact URL that fails, then add or reorder a component so the first rule that matches it is the one you mean.

5. Is iOS still caching the old file?

Caching means the fix is live on your server but not on the device: Apple's CDN requests the file within 24 hours and devices check for updates about once a week after install (Apple Developer, Supporting associated domains). TN3155 says "There is no direct CDN invalidation option." Reinstall the app on test devices to fetch the newer copy at once. While testing, add ?mode=developer to the entitlement, as in applinks:example.com?mode=developer, so the device reads the file from your server and skips the CDN. In a sysdiagnose, the swcutil_show.txt file gives "Last Checked" and "Next Check" for the domain. Branch's help page says iOS doesn't re-read the file unless the app is reinstalled or updated; Apple's newer TN3155 gives the weekly check beside the reinstall.

Tapped in the browser means the setup is right but the tap happened where iOS chooses the browser on purpose, and the Notes test offers the app. TN3155 says a URL typed into the address bar "will never open the app", and a link to the same domain as the page already open in Safari stays in Safari. Branch's help page adds a link fired by JavaScript without a user action, and TN3155 notes that "Universal links may not be enabled in every web browser." Test from Notes, Mail or Messages, and put links meant to leave your own site on another subdomain with its own file, as TN3155's login example does.

Wrapped means an email or ad tool sent the click through its own domain, so the link the person tapped isn't a Universal Link. TN3155 says redirection "is allowed, although not preferred, when opening universal links from another app", and the person is "routed through the web browser to the app". Branch's help page says wrapped links won't open the app "in most cases". Send the Universal Link unwrapped, or wrap it on a domain that is itself in the entitlement with its own file.

Chosen means the person picked Safari once and iOS remembered it for the domain. TN3155 says the option chosen on a long-press "will set the default behavior for your device when following universal links from this domain in the future", and Branch's help page says tapping the domain at the top right after a Universal Link opens the app stops iOS from using Universal Links for it. This is the case where universal links open Safari on one device and the app on others. In a sysdiagnose, "User Approval" records the person's choice, while "Site/Fmwk Approval" records whether Apple's CDN approved the file and matched the pattern, which splits this cause from a server problem. Long-press the link and choose to open it in the app, or tap OPEN on the Smart App Banner, as Apple's QA1916 says.

9. Does the app reject the URL?

Rejected means iOS opened the app but it shows the wrong screen or none, because the handler returned false or never read the activity. QA1916 lists the app returning false from application(_:continueUserActivity:restorationHandler:) among the causes. An app that uses scenes gets the link in scene(_:willConnectTo:options:) when it isn't running and in scene(_:continue:) when it is (Apple Developer, Supporting universal links in your app). Handle NSUserActivityTypeBrowsingWeb in both scene methods, and log the URL each one receives.

How do you confirm the fix on a real device?

You confirm the fix on a real device by running the same path a person will take, after the file is fixed and fetched again:

  1. Validate the hosted file.

  2. Reinstall the app, so the device fetches the new file.

  3. Long-press the link in Notes and check both options show.

  4. Open the link from Mail and Messages.

  5. Check the app shows the screen the link points to.

Check the file again after every deploy, since a new redirect or header rule can break it at any time. Smler's free AASA validator reports each check pass or fail, and the guide to Universal Links covers the full set of tests.

Android App Links fail for some of the same reasons: a redirect on the file, a host with no file of its own and a person's earlier choice break both, while a wrong signing certificate fingerprint is a cause of Android's own. The Android checks and fixes are in Android App Links not working.