DEV Community

OrbitKit
OrbitKit

Posted on Originally published at orbitkit.io AI-assisted

Universal Links not working? A debugging checklist for iOS

The most frustrating thing about iOS Universal Links is that when they break, iOS gives you no error message. The link just opens Safari. Your app doesn't launch. There's nothing in the console to tell you why.

When that happens, the cause is almost always one of twelve things, once you've ruled out testing it wrong (step 0). This is the systematic checklist to walk through them, starting with the ones a single curl command can settle. Most of the checks come straight from Apple's own troubleshooting note, TN3155, and its associated-domains documentation; the rest are hosting pitfalls those pages don't cover.

Run through it top to bottom. Stop when something fails — that's almost certainly your problem.

Looking for the full list of files and URLs your iOS app needs before App Store submission, not just Universal Links? See the complete checklist of App Store required pages.

0. First: confirm you're testing correctly

Before you assume Universal Links are broken, make sure you're not just testing them wrong:

  • Don't paste the link into Safari's address bar. Safari treats those as in-Safari navigations and won't trigger Universal Links. Send yourself the link via Notes, Messages, or Mail. Long-press it.
  • You should see "Open in <App Name>" as the first option in the long-press menu. If you only see "Open in Safari", Universal Links aren't activating.
  • Test on a real device. Apple's own test steps in TN3155 (the long-press in Notes, the Associated Domains diagnostics under Settings > Developer) are written for a device, so check there before you trust a result.

1. Is the AASA file reachable at the canonical URL?

curl -I https://your-domain.com/.well-known/apple-app-site-association
Enter fullscreen mode Exit fullscreen mode

You should see HTTP/2 200. If you see 404, your file is missing or at the wrong path. If you see 301 or 302, you have a redirect — see #2.

Also test the legacy root path, which third-party validators check:

curl -I https://your-domain.com/apple-app-site-association
Enter fullscreen mode Exit fullscreen mode

Modern iOS uses /.well-known/, but some validators flag a missing root-path file as a setup error. Easiest fix: serve both.

2. Are there any redirects in the way?

Apple's swcd will not follow 301 or 302 responses for the AASA file. The file must be at the canonical URL with a direct 200.

Common offenders:

  • HTTP-to-HTTPS redirects. Apple's CDN always requests HTTPS, so this rarely matters — but if you're testing in dev, make sure you're hitting HTTPS directly.
  • Trailing-slash redirects. Some web servers redirect /folder → /folder/. Make sure the AASA URL doesn't get redirected.
  • Apex-to-www redirects (or the reverse). If your DNS redirects myapp.com → www.myapp.com, the AASA file at myapp.com/.well-known/apple-app-site-association will fail.

The fix: serve the file directly from the canonical URL, no redirect chain.

3. Is the Content-Type header exactly application/json?

curl -I https://your-domain.com/.well-known/apple-app-site-association | grep -i content-type
Enter fullscreen mode Exit fullscreen mode

We recommend content-type: application/json. Apple's current documentation doesn't name a Content-Type for this file; its earlier guides did (the archived Handoff guide says the file "may be a JSON file with a MIME type of application/json"), so that's the type to serve. If you see something else:

  • text/plain or application/octet-stream — not the type Apple described; fix it before you look further. GitHub Pages picks the type from the file extension and doesn't let you set one per file, so an extension-less file there needs a different host.
  • application/json; charset=utf-8 — still JSON, but bare application/json is the safe choice

4. Does the file have a .json extension?

It must not. The filename is literally apple-app-site-association with no extension. If your editor or build process appended .json, Apple's swcd won't find it at the expected path.

curl -I https://your-domain.com/.well-known/apple-app-site-association.json
Enter fullscreen mode Exit fullscreen mode

If that returns 200 but the no-extension URL returns 404, that's your problem.

5. Is the JSON actually valid?

curl -s https://your-domain.com/.well-known/apple-app-site-association | jq .
Enter fullscreen mode Exit fullscreen mode

If jq errors, your JSON is broken. Common issues:

  • Trailing commas in arrays or objects (legal in JS, illegal in JSON)
  • Single quotes instead of double quotes
  • Unquoted keys
  • A BOM (byte-order mark) at the start of the file from Windows-edited files

6. Does the App ID format match exactly?

The appIDs array entries must be in TEAMID.bundleid format:

"appIDs": ["ABCDE12345.com.yourcompany.yourapp"]
Enter fullscreen mode Exit fullscreen mode
  • The Team ID is exactly 10 alphanumeric characters (uppercase letters and numbers).
  • The bundle ID must match what's in your Xcode project's Bundle Identifier field exactly. Case-sensitive.
  • A common typo: using a lowercase Team ID. Apple's are always uppercase.

You can find your Team ID in Apple Developer → Membership.

7. Does the Xcode Associated Domains entitlement match?

In Xcode, select your app target → Signing & Capabilities → Associated Domains. You should see:

applinks:your-domain.com
Enter fullscreen mode Exit fullscreen mode
  • No https:// or http:// prefix.
  • No trailing slash.
  • For subdomains, each one needs its own entry: applinks:myapp.com and applinks:www.myapp.com are different.
  • If you removed the capability and re-added it, delete the app from your device and reinstall — iOS caches the entitlement.

8. Is Apple's CDN serving a stale version?

Starting in iOS 14, devices don't fetch the AASA file directly. Apple's CDN does it on their behalf, then devices pull from there. Apple's associated-domains documentation puts numbers on it: its CDN "requests the apple-app-site-association file for your domain within 24 hours", and "devices check for updates approximately once per week after app installation." So freshly-deployed AASA changes can take a while to propagate.

To see what the CDN currently has for your domain, hit:

https://app-site-association.cdn-apple.com/a/v1/your-domain.com
Enter fullscreen mode Exit fullscreen mode

If this shows your old file, the CDN hasn't refreshed yet. To bypass it during development, change your Xcode Associated Domains entitlement from:

applinks:your-domain.com
Enter fullscreen mode Exit fullscreen mode

to:

applinks:your-domain.com?mode=developer
Enter fullscreen mode Exit fullscreen mode

That tells iOS to skip the CDN and fetch the file directly from your origin. Remove the ?mode=developer flag before submitting to the App Store — it's a development-only mode.

9. Did iOS actually re-fetch the AASA after your change?

A device doesn't pick up a changed AASA file right away: per TN3155, it downloads the file when the app is installed and then checks for updates about once a week. To force a refresh during development, delete and reinstall the app. That's Apple's own instruction ("To download a newer version of the AASA file, reinstall the app"), and TN3155 adds that there is no way to invalidate the CDN's copy.

10. Is something blocking Apple's AASA-Bot user agent?

Apple's documentation tells you which user agents to let through: the App Clip setup page says to allow AASA-Bot and CFNetwork, and TN3155 says your server "should accept all user agent requests". Some bot-protection layers will block them:

  • Cloudflare with "I'm Under Attack" mode or aggressive bot challenges. Allow AASA-Bot explicitly, or exempt the AASA path from the challenge.
  • AWS WAF rules that challenge or block bots.
  • Custom IP allowlists. Apple doesn't publish its CDN's address ranges (TN3155: they "cannot be guaranteed"), so the file has to be reachable from any IP.

Check your origin logs for AASA-Bot requests. If you don't see them, something's blocking the bot before it reaches your app. TN3155's quick test is to request the file with a made-up user agent, curl -A "MyAgent-Bot/*" https://your-domain.com/.well-known/apple-app-site-association, and confirm it still comes back.

11. Are your URL paths actually matching?

If swcd fetches the file successfully and your app entitlement is correct, but Universal Links still don't open the app, the path patterns in your AASA file probably don't match the URL you're testing.

"components": [
  { "/": "/products/*" }
]
Enter fullscreen mode Exit fullscreen mode

This matches /products/123 and /products/, but not /products (no trailing slash). Common pitfalls:

  • * matches zero or more characters, so /products/* still needs the slash. Add a second component for /products, or use /products* if you don't mind it matching /products-old too.
  • Patterns are case-sensitive by default. /Products/ won't match /products/* unless you set "caseSensitive": false.
  • Query strings and fragments (?utm_source=x, #section) don't affect the match unless the component has its own "?" or "#" pattern.

For wide-open testing, use "/": "*" (matches every path) to confirm the rest of your config works, then narrow down to specific patterns.

12. The "I just changed it and it stopped working" case

If everything was fine yesterday and stopped working today, scan your recent changes for:

  • A web server config change (new redirect, new Cache-Control rule, new bot challenge)
  • A DNS change (new CNAME, new Cloudflare proxy enabled)
  • An SSL cert that expired or rotated to a different issuer
  • A Cloudflare "Always Use HTTPS" toggle
  • An app deploy that changed your build's bundle ID
  • A new web framework (Next.js / Nuxt / etc.) that started routing the well-known path through application code instead of serving it as a static file

This last one is sneaky: many web frameworks intercept all paths by default. They'll serve a 404 page (with Content-Type: text/html) for /.well-known/apple-app-site-association instead of letting your static file be found.

A condensed diagnostic flow

If you want to walk through it fast:

# 1. File reachable, 200, no redirect
curl -I https://your-domain.com/.well-known/apple-app-site-association

# 2. Correct content-type
curl -I https://your-domain.com/.well-known/apple-app-site-association | grep -i content-type

# 3. Valid JSON, expected appIDs
curl -s https://your-domain.com/.well-known/apple-app-site-association | jq .

# 4. CDN sees the same content
curl -s https://app-site-association.cdn-apple.com/a/v1/your-domain.com | jq .

# 5. Branch's validator runs through everything
open https://branch.io/resources/aasa-validator/
Enter fullscreen mode Exit fullscreen mode

If all five pass and Universal Links still don't work, it's almost certainly the Xcode entitlement (#7) or a stale device cache (#9 — delete and reinstall).

Further reading


I run OrbitKit, which hosts your AASA file with every server-side gotcha in this checklist handled by default — served at both paths, application/json enforced, zero redirects, auto-SSL, no bot-challenge layer, 128 KB size guard, and the file generated from a typed config so there are no JSON syntax errors. This post was originally published on the OrbitKit blog.

Top comments (0)