# Universal Links not opening the app: 12 causes, in the order to check them

> Your Universal Link opens Safari, or opens the app on the wrong screen. Twelve causes in the order we check them, from how you tapped to the entitlement, Apple's CDN and your app delegate, with Apple's own test steps and a command for each.

Source: https://straitlink.in/blog/universal-links-not-opening-causes/

**The short answer:** when a Universal Link opens Safari instead of your app, check the way you tested before you touch the server. Apple's own test is to paste the link into Notes and long-press it. If "Open in" your app appears, the setup works and the problem is where or how the link was tapped. If it doesn't appear, the cause is the entitlement, the `apple-app-site-association` file or Apple's cached copy of it.

This post walks the whole chain, from the tap to your app's code, in the order we check it. Two of the twelve causes are about the association file itself. Our post on [apple-app-site-association problems](https://straitlink.in/blog/apple-app-site-association-not-working-fixes/) covers those in depth, with nine file-level checks. Everything here comes from Apple's technote [TN3155: Debugging universal links](https://developer.apple.com/documentation/technotes/tn3155-debugging-universal-links) and Apple's developer documentation unless we say it's our own test.

## First, the 30-second test

1. Paste the link into the **Notes** app on the iPhone.
2. Long-press it.
3. Look for two options: open in your app, and open in Safari.

TN3155 says that if Universal Links are set up correctly, "the option to open in your app and in the web browser will both show up." Whichever you pick becomes the default for that domain on that phone.

On iOS you can go further. Turn on Developer Mode, then **Settings → Developer → Associated Domains Development**, and open **Diagnostics** to type a full URL. The phone tells you whether the link is valid for an installed app.

- **Both options show:** start at cause 1.
- **Only Safari shows:** skip to cause 6.

## The link works, but the way it was tapped doesn't open the app

### 1. The URL was typed or pasted into Safari's address bar

TN3155 is plain about this: entering the URL in the address bar "will never open the app, as this is direct navigation within the web browser." Tap the link from Notes, Messages or Mail instead.

### 2. The link is on the same domain as the page you're on

Apple's guide to [linking to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) says a tap on a Universal Link "in the same domain" stays in Safari, "respecting the user's most likely intent to continue within the browser." A tap on a link in a different domain opens the app. So an "Open in app" button on `example.com` that links to `example.com/login` won't open the app. TN3155's fix is a separate subdomain for those links, such as `go.example.com`, with its own entitlement entry and its own association file.

### 3. Someone chose Safari once

The long-press menu sets a default per domain. If you or a tester once picked the browser, every later tap on that domain opens Safari on that phone. Repeat the Notes long-press and choose your app. A sysdiagnose shows this choice as the `User Approval` field in `swcutil_show.txt`.

### 4. The tap happened in a browser or app that doesn't hand links to apps

TN3155 says it's "up to third-party web browsers" to support Universal Links, and that "Safari implements all of the function described in this technote." Chat and social apps that open links in their own in-app browser are the common case: your app never sees the tap. Our post on [Instagram and WhatsApp links opening the browser](https://straitlink.in/blog/instagram-whatsapp-links-open-browser-not-app/) goes through those apps one by one.

### 5. The link people tap isn't on your associated domain

Email click tracking, shorteners and ad redirects wrap your URL in their own domain, which isn't in your entitlement. TN3155 notes that when the tapped link "is not a universal link but redirects to one, the user will be routed through the web browser to the app." That's a trip through Safari, not a direct open. Turn off link wrapping for those links, or put your associated domain on the link people actually tap. [Deep links in email](https://straitlink.in/blog/deep-links-in-email-click-tracking/) shows how this works for the common email tools.

## The phone doesn't know the app owns the domain

### 6. The entitlement is missing, misspelled or has extra parts

Open the app target's **Signing & Capabilities** tab and check **Associated Domains**. Each entry should look like `applinks:links.example.com`. Apple's [associated domains guide](https://developer.apple.com/documentation/xcode/supporting-associated-domains) says to include only the domain, without "path and query components or a trailing slash". TN3155 adds that a port, as in `applinks:example.com:8080`, "will not open your app." Also check that you added the capability to the target you're running, and that a staging build with a different bundle ID has its own entries.

### 7. The domain and the file location don't match

Each domain in the entitlement needs a file on that exact host. TN3155 explains the wildcard rule. A file at `example.com` covers `applinks:example.com` and `applinks:*.example.com`, but it "will not work with specific subdomains like `applinks:www.example.com`". Those need their own file at `https://www.example.com/.well-known/apple-app-site-association`.

### 8. Apple's CDN can't fetch the file

Since iOS 14, phones don't download the file from your server. Apple's guide says they ask "an Apple-managed content delivery network (CDN) dedicated to associated domains." If that CDN gets a redirect, a `403` or `404`, a bot challenge or a timeout, the association fails. TN3155 asks for the file to be reachable "from any IP address", with no redirect, and says your server "should accept all user agent requests."

Apple's docs don't publish a way to see what the CDN holds. Developers use this URL, which Apple's CDN answers:

```bash
curl -sI https://app-site-association.cdn-apple.com/a/v1/links.example.com
```

When we ran it on 24 October 2026, a domain with a working file returned `200` with the JSON, an `Apple-From` header naming the URL it was fetched from, and a `Cache-Control` max-age of about six hours. A domain with no file returned `404` with `Apple-Failure-Reason: SWCERR00101 Bad HTTP Response: 404 Not Found`. This endpoint is undocumented, so read it as a hint, not a verdict. The free [AASA validator](https://straitlink.in/tools/aasa-validator/) checks your own server's response, which is what the CDN copies.

## The file is fetched, but it doesn't say yes to this app

### 9. The file names the wrong app or doesn't match the path

The file must list the app as `<Team ID>.<bundle ID>`, and its `components` or `paths` must match the URL. Apple checks patterns in order and the first match wins, so a broad exclusion near the top blocks everything below it. TN3155 also warns against mixing the modern `appIDs`/`components` format with the older `appID`/`paths` one. On a Mac, `swcutil` tests a URL against a file:

```bash
sudo swcutil verify -d links.example.com -j ./aasa.json -u https://links.example.com/p/42
# Pattern "https://links.example.com/p/42" matched.
```

The [AASA post](https://straitlink.in/blog/apple-app-site-association-not-working-fixes/) covers the other file problems: invalid JSON, the wrong content type, a byte-order mark, a signed or compressed file.

### 10. The phone still has the old answer

Apple's guide says the CDN requests your file "within 24 hours", and TN3155 says phones download it when the app is installed and check for updates "approximately once per week" after that. "There is no direct CDN invalidation option." Reinstall the app to make the phone fetch the file again, and allow for the CDN's own delay before you decide the fix didn't work.

### 11. A development build skips the CDN, or a release build still tries to

While you develop against a server the CDN can't reach, Apple offers an alternate mode: add `?mode=developer` to the entitlement entry, as in `applinks:dev.example.com?mode=developer`. The [entitlement reference](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.associated-domains) says this fetches the file directly from your server, but only for apps signed with a development profile, on devices where the user has opted in. On an iPhone, that opt-in is the Associated Domains Development switch from the test above. TestFlight and App Store builds aren't signed with a development profile, so they can't use this mode, and a domain that only works this way will never open the release app. Remove the suffix before you ship, and make sure the release domain passes cause 8.

## The app opens, but on the wrong screen

### 12. The app doesn't read the link it was given

If the app opens on its home screen, the link worked and the app ignored it. Apple's guide to [supporting universal links in your app](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) says the system sends an `NSUserActivity` with the type `NSUserActivityTypeBrowsingWeb`, and the URL is in `webpageURL`. Where it arrives depends on your app:

| Your app | App not running | App running or in the background |
|---|---|---|
| Uses scenes | `scene(_:willConnectTo:options:)`, in `connectionOptions.userActivities` | `scene(_:continue:)` |
| No scenes | `application(_:continue:restorationHandler:)` | The same method |

A common miss is an app that handles `scene(_:continue:)` but ignores the user activity in `scene(_:willConnectTo:options:)`, so links work only when the app is already open. Apple also warns that Universal Links are "a potential attack vector into your app", so validate every parameter and drop malformed URLs.

## Still opening Safari after all twelve?

Take a sysdiagnose from the phone with the app installed, open `swcutil_show.txt` and find your app ID. TN3155 explains the fields. `Site/Fmwk Approval: approved` means the CDN fetched and matched your file. `unspecified` or `denied` sends you back to causes 6 to 8.

On Strait, your link domain serves `apple-app-site-association` for you from the Team ID and bundle ID you save in **Dashboard → Apps & stores**, with a `200`, no redirect and `application/json`, which takes care of cause 8 for that domain. Causes 1 to 5 and 12 are about the tap and your app, so they apply with any provider. The [App Links docs](https://straitlink.in/docs/app-links/) show what we host, and the [iPhone status page](https://straitlink.in/iphone-status/) says what we've tested on real iPhones. For Android, the same symptom has its own guide: [Android App Links verification failed](https://straitlink.in/blog/android-app-links-verification-failed/).

## Frequently asked questions

### Why does my Universal Link open Safari instead of my app?

Most often the link was typed into Safari's address bar, tapped on the same domain, or tapped in an in-app browser. Test by pasting it into Notes and long-pressing. If no "open in app" option appears, check the entitlement, the association file and Apple's cached copy.

### How long does Apple take to pick up a changed apple-app-site-association file?

Apple says its CDN requests your file within 24 hours, and phones check for updates about once a week after install. There's no way to clear the CDN. Reinstalling the app makes the phone fetch the file again.

### Do Universal Links work in Chrome, Instagram or WhatsApp?

Apple leaves it to each browser. Safari supports everything Apple describes. In-app browsers often open the web page instead, so test from Notes first, then from the apps your users share in.

### What does the developer alternate mode do?

Adding `?mode=developer` to an Associated Domains entry makes a development build fetch the association file directly from your server instead of Apple's CDN. It works only for apps signed with a development profile, on phones with developer mode turned on, so remove it before release.

## Sources and how we checked

- Apple, [TN3155: Debugging universal links](https://developer.apple.com/documentation/technotes/tn3155-debugging-universal-links): the Notes test, Developer → Diagnostics, typed URLs, same-domain taps, third-party browsers, redirects, wildcard and port rules, user-agent policy, `swcutil`, sysdiagnose fields and CDN refresh timing. Read on 24 October 2026 (revision of 15 May 2025).
- Apple, [Supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains): the entitlement format, no path or trailing slash, one file per subdomain, the CDN since iOS 14 and the 24-hour CDN request. Read on 24 October 2026.
- Apple, [Associated Domains Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.associated-domains): the `developer`, `managed` and `developer+managed` alternate modes.
- Apple, [Allowing apps and websites to link to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) and [Supporting universal links in your app](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app): same-domain behaviour, `NSUserActivity`, the scene and app delegate methods, and the warning to validate parameters.
- Our own requests on 24 October 2026 to `app-site-association.cdn-apple.com` for a domain with a file and one without: the status codes and the `Apple-From`, `Apple-Failure-Reason` and `Cache-Control` headers quoted above. Apple doesn't document this endpoint.
