Universal Links stopped working

Definition

Universal Links that previously worked and no longer do have almost always been broken by a change outside the app: a per-domain user preference, a signing or infrastructure change, or Apple's CDN refreshing its cached copy of a file that was already broken.

A regression is a different diagnostic problem from a setup that never worked, because the space of causes is not "everything that can be wrong" but "everything that changed". That is a much smaller list, and the most common entry on it is not a change you made — it is a preference one user set on one device by tapping something they did not understand. Work out first whether this is happening to everyone or to one person, because that single fact splits the list in half.

One device, or everyone?

Ask this before anything else. It is the cheapest question available and it eliminates most of the page.

The user preference nobody knows exists

When a Universal Link opens your app, iOS shows a small breadcrumb in the top-right of the status bar with the domain name on it. Tapping that breadcrumb returns the user to Safari — and it also records a per-domain preference that says: from now on, open this domain in Safari rather than the app. The user is never told this. From their point of view they tapped a back button once, and Universal Links quietly stopped working for your entire domain, permanently.

The same preference is set by long-pressing a link and choosing Open instead of Open in “App”. Both are things users do by accident, and neither is discoverable in Settings — there is no toggle anywhere in iOS that lists or resets these preferences.

Deleting and reinstalling the app also clears it, which is why support's default advice appears to work and produces no useful information about the real cause. If a reinstall fixes it for one user and the problem does not recur across your install base, this was it.

The changes that break it for everyone

A redirect appeared in front of the association file. The most common site-wide regression by a wide margin, and it is almost never deliberate — an added locale prefix, a new trailing-slash normaliser, a www canonicalisation, or a CDN rule. Apple's fetcher does not follow redirects, so a 301 is a failure. The web team's change log is the place to look, not the app's.

The App ID Prefix or bundle identifier changed. Transferring an app between developer accounts, or being migrated onto a new Team ID, changes the App ID in ways that make the deployed AASA file stale while remaining perfectly valid JSON. Nothing errors — the file simply names an app that no longer exists.

An app update shipped without the entitlement. A regenerated provisioning profile that lost the Associated Domains capability, or a CI signing change, produces a build that cannot claim the domain. The tell is that the break correlates exactly with a release, and only affects users who took the update.

Apple's CDN finally refreshed. This one is genuinely counter-intuitive: you broke the file weeks ago, the CDN kept serving its cached good copy, and everything worked until the refresh. The change that caused the outage and the outage itself can be separated by weeks, which makes the deploy correlation misleading. Always compare the CDN copy with your origin rather than assuming they agree.

# Apple's cached copy — what devices are actually being given
curl -sS https://app-site-association.cdn-apple.com/a/v1/example.com \
  | python3 -m json.tool > /tmp/cdn.json

# Your origin, no redirects followed, so a 301 shows up as a 301
curl -sS --max-redirs 0 \
  https://example.com/.well-known/apple-app-site-association \
  | python3 -m json.tool > /tmp/origin.json

diff /tmp/cdn.json /tmp/origin.json && echo "in sync"

# Headers only: one 200, application/json, nothing else
curl -sSI --max-redirs 0 \
  https://example.com/.well-known/apple-app-site-association

The TLS certificate expired or the chain changed. The fetch requires a valid, trusted certificate. An expired intermediate, or a certificate that browsers accept because they have a cached chain, will fail a fetch that has no such cache. Renewals that "worked fine, the site is up" are a recurring source of this.

`?mode=developer` was left in a release build. It bypasses the CDN and makes every device fetch your origin directly. It survives review, works in testing, and turns your origin into a dependency of every app launch — which fails the first time that host has a bad day.

Making the regression impossible to repeat

Six of the causes above are infrastructure, and infrastructure changes are made by people who have no reason to know that a JSON file in .well-known is load-bearing for the mobile app. The durable fix is not vigilance, it is a check that fails on the deploy that introduces the problem.

1. Assert in CI that curl -sSI --max-redirs 0 against production returns exactly 200 with Content-Type: application/json. This catches the redirect regression, the auth-wall regression, and the SPA-catch-all regression on the deploy that causes them.
2. Assert the App ID in the deployed file matches the one in the app's entitlement, so a Team ID migration fails the build rather than the links.
3. Add a certificate expiry alert on the host serving the file, separate from any alert on the marketing site.
4. Add ?mode=developer to the list of strings your release pipeline greps for and refuses to ship.
5. Put the long-press fix in your support macros, so the per-device preference stops arriving as an engineering escalation.