BlogiPhone

apple-app-site-association not working? Nine causes and how to check each one

· 8 min read · By the Strait team

Your Universal Links open Safari instead of your app. Here are the nine apple-app-site-association problems we see most, how Apple's CDN changes debugging, the commands that show each one, and how to tell a file problem from a testing mistake.

Universal Links fail quietly. Nothing crashes and no error appears on screen: a tap on your link opens Safari instead of the app, and the app never learns that it happened. In most cases the cause is the apple-app-site-association file (AASA for short), the way it's served, or the way the link was tested.

This post lists the nine causes we see most, in the order we check them, with the command that shows each one. Most of the rules come from Apple's technote TN3155: Debugging universal links and its guide to supporting associated domains. The checks are the same ones our free AASA validator runs. If the file passes and links still open Safari, the cause is usually the tap or the app, not the file: Universal Links not opening: 12 causes covers those.

Your app declares the domains it may open in the Associated Domains entitlement, as applinks:links.example.com. Your website publishes a JSON file at https://links.example.com/.well-known/apple-app-site-association that names your app and the URL paths it may open. When the app is installed, iOS checks that both sides agree.

Since iOS 14, the phone doesn't fetch the file from your server. Apple's guide says apps "send these requests to an Apple-managed content delivery network (CDN) dedicated to associated domains." The technote adds that the phone downloads the file from the CDN when the app is installed and checks for updates "approximately once per week" after that. There's no way to clear the CDN's copy yourself. Keep this in mind for every fix below: a corrected file can take a while to reach a phone, and reinstalling the app is the way to make the phone fetch it again.

1. The file sits behind a redirect

This is the most common failure. The technote is direct: if the response is a 301 or 302, the file is behind a redirect, "which is not supported when hosting the AASA file."

The usual cause is a site-wide rule, such as example.com redirecting to www.example.com, or http to https with a trailing-slash rewrite. A browser follows the redirect and shows you the JSON, so the file looks fine when you open it.

Check with curl, without following redirects:

Terminal
curl -sI https://links.example.com/.well-known/apple-app-site-association
# HTTP/2 200
# content-type: application/json

You want 200 on the first line. If you use both the bare domain and www, serve the file on each one separately.

2. The domain in the entitlement doesn't match the file's location

Each domain in your entitlement needs its own file. Apple's guide says sites with several subdomains need an entry for each, and "each must serve its own apple-app-site-association file." The technote spells out the wildcard case. A file at example.com covers applinks:example.com and applinks:*.example.com. It doesn't cover a specific entry such as applinks:www.example.com, which needs a file on www.example.com.

Two smaller rules from the same technote: an entitlement domain can't contain a port (applinks:example.com:8080 won't open your app), and it should have no path, query or trailing slash.

3. A firewall, bot rule or geo-block refuses the request

A 403 or 404 usually means your site refused the request. The technote asks for the file to be reachable "in all geographical locations, from any IP address," and says your server "should accept all user agent requests." Apple doesn't publish the CDN's IP ranges.

Bot protection is the usual suspect. A rule that challenges unknown user agents, a country block or a login wall on a staging domain will all stop Apple's CDN. The technote suggests testing with a made-up user agent:

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

If that returns an HTML challenge page instead of JSON, add an exception for the /.well-known/ path.

4. The JSON is invalid, signed, compressed or saved with a BOM

The file must be plain JSON. Things that break it:

  • A syntax error, often a trailing comma after hand editing. Run the file through python3 -m json.tool.
  • A signed file. Signing was needed before iOS 9. A signed (PKCS#7) file isn't plain JSON.
  • Gzip bytes without the header. A server that stores the file compressed but doesn't send Content-Encoding: gzip serves unreadable bytes.
  • A byte-order mark at the start, added by some Windows editors.
  • A .json extension. Apple's guide says to name the file apple-app-site-association "without an extension."

Our validator reports each of these, and it also treats a file over 128 KB as an error, because a long list of individual paths is a sign that wildcards or components rules would do the job.

5. The content type is wrong

Serve the file as Content-Type: application/json. Because the file has no extension, many servers guess application/octet-stream or text/plain. Set the type explicitly for that one path. In nginx, for example, a location block for /.well-known/apple-app-site-association with default_type application/json; does it.

6. The app ID is wrong

Each app is named as <Team ID>.<bundle ID>, such as ABCDE12345.com.example.app. The mistakes we see:

  • The Team ID of a different team, often an agency's or a previous company's account. Copy it from your Apple Developer account's Membership page.
  • A bundle ID that doesn't match the build being tested. A debug build with a .dev suffix is a different app.
  • An example value left in from a tutorial, such as ABCDE12345 or com.example.

7. The paths or components don't match the URL

The modern format uses appIDs (a list) and components (a list of rules). The older format uses appID (a string) and paths. The technote advises: "Please avoid mixing formats."

JSON
{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/admin/*", "exclude": true },
          { "/": "*" }
        ]
      }
    ]
  }
}

Apple's reference for components says the order of the patterns is the order iOS checks them, and "the first match wins", so exclusions go before the catch-all. A pattern that doesn't start with / or * almost never matches. On a Mac you can test a pattern against a URL with Apple's swcutil, as described in the technote:

Terminal
sudo swcutil verify -d links.example.com -j ./aasa.json -u https://links.example.com/summer

The free AASA generator writes the file with exclusions in the right order.

8. You tested it in a way that never opens the app

This isn't a file problem, but it causes many false alarms. From the technote:

  • Typing or pasting the URL into Safari's address bar "will never open the app, as this is direct navigation within the web browser."
  • Tapping a link on the same domain you're already browsing keeps you in Safari. Apple's article on linking to your content explains this respects "the user's most likely intent to continue within the browser." Use a separate subdomain for links that should open the app from your own site.
  • The user chose Safari once. A long press on a Universal Link offers to open it in the app or in the browser, and the choice becomes the default for that domain on that phone.
  • Other browsers decide for themselves whether to support Universal Links. The technote says Safari implements all of the behaviour it describes.

Apple's suggested test is to paste the link into the Notes app and long-press it. If both an "open in app" option and a browser option appear, the link is set up correctly. On iOS you can also turn on Developer Mode, then Settings → Developer → Associated Domains Development, and use its Diagnostics screen to check a URL against the installed app.

9. The CDN still has an old copy

If the file is correct now but wasn't yesterday, the phone may still hold the old result. Reinstall the app to make it fetch the file again. While developing, Apple offers an alternate mode that skips the CDN: add ?mode=developer to the entitlement domain (applinks:links.example.com?mode=developer). Apple's guide says it works only for apps signed with a development profile, on devices where the user has opted in. Remove it before release.

Reading the result on a device

When the file checks out but the link still opens Safari, the technote suggests a sysdiagnose from the phone. Its swcutil_show.txt lists each associated domain with a Site/Fmwk Approval field. approved means the CDN fetched and matched your file. unspecified or denied points back to causes 1 to 3.

How Strait handles the file

On Strait, your link domain (<handle>.strait.link) serves apple-app-site-association and assetlinks.json for you, built from the Apple Team ID and bundle ID you save in Dashboard → Apps & stores. The file is served with a 200, no redirect, as application/json, and at both /.well-known/ and the old root location. Until both IDs are saved, the address answers 404, which the validator reports. The App Links and Universal Links docs show what we host and how to check it.

To be clear about where we stand on iPhone: serving the file is plain web hosting, and our Universal Links were tested on a real iPhone (iOS 26) in October 2026. Deferred deep links after an install are different: install matching is opt-in (off until you turn it on in Settings → iPhone installs) and proven on iPhone simulators; the real-iPhone run waits on our App Store listing. The iPhone status page says what that means for a campaign today.

Sources and how we checked

  • Apple, TN3155: Debugging universal links: redirects not supported, 403/404 and user-agent policy, wildcard and subdomain rules, no ports, the Notes long-press test, typed URLs never opening the app, swcutil, sysdiagnose fields, and CDN refresh behaviour. Read on 5 October 2026.
  • Apple, Supporting associated domains: file name without an extension, .well-known location, HTTPS with no redirects, one file per subdomain, the CDN since iOS 14 and the alternate developer mode.
  • Apple, applinks components reference: patterns are checked in order and the first match wins.
  • Apple, Allowing apps and websites to link to your content: links on the same domain stay in Safari.
  • The checks described (redirect, status, content type, JSON, BOM, signing, gzip, app ID, placeholders, components, size, legacy location) are the rules in our engine's App Links checker, which the AASA validator and the App Links checker run. How our link domain serves the file comes from our engine's code.