Deep Link Doctor
Home / Developer notes

AASA file is behind a redirect or blocked

Apple does not follow redirects on the AASA URL and its CDN must reach your server from anywhere. Fix 301, 302, 403 and 404 errors that break universal links.

SymptomUniversal links open Safari and curl on the AASA URL shows a 301, 302, 403 or 404.
Likely causeThe file is served through a redirect, or a firewall, bot rule or geo block stops Apple's CDN from fetching it.
FixServe the file with a 200 directly at every domain in the entitlement, open to all IPs, regions and user agents.

Short answer: Apple requires the apple-app-site-association file over HTTPS "with a valid certificate and with no redirects". A redirect from the apex to www, from HTTP to HTTPS, or a firewall that blocks Apple's CDN all stop iOS reading the file. Serve it with a 200 at every domain in the entitlement.

What is happening

AASA delivery failure: Apple's CDN cannot fetch the apple-app-site-association file with a direct 200 response, so iOS has no rules for that domain.

Since iOS 14 and macOS 11, devices do not fetch the file from your server. Apple says they request it from "an Apple-managed content delivery network (CDN) dedicated to associated domains", which fetches from your server. So the CDN has to reach you.

  • Apple's technote says a 301 or 302 on the file is "not supported".
  • A 403 or 404 means "your site denied access".
  • The file must be reachable "in all geographical locations, from any IP address", and the server "should accept all user agent requests".
  • In a sysdiagnose, swcutil_show.txt shows Site/Fmwk Approval for each domain; approved means the CDN fetched and matched the file.

Why does this happen?

Redirects are usually set up site-wide and catch the /.well-known/ path by accident. Blocks come from security tools that treat Apple's fetcher as a bot.

  • Apex to www: example.com redirects to www.example.com, but the entitlement says applinks:example.com.
  • Trailing slash or extension rewrites that send the file to another URL.
  • WAF or bot rules that challenge unknown user agents.
  • Geo or IP allowlists that exclude the regions or ranges Apple's CDN uses.
  • Wrong file name: uploading only apple-app-site-association.json, which returns a 404 at the real URL.

How to confirm it

  1. Run curl -v https://example.com/.well-known/apple-app-site-association. Look for HTTP/2 200 with no Location header.
  2. Repeat for every domain in the entitlement, including www and other subdomains.
  3. Test the user agent policy with Apple's suggested check: curl -A "MyAgent-Bot/*" https://example.com/.well-known/apple-app-site-association.
  4. Optionally, check what Apple's CDN holds with curl -i https://app-site-association.cdn-apple.com/a/v1/example.com. The Apple-From header shows the origin URL it fetched. This CDN URL is not on an Apple documentation page.

How to fix it

  1. Exclude /.well-known/apple-app-site-association from site-wide redirect rules.
  2. Serve the file directly on each host in the entitlement. A file on example.com does not cover applinks:www.example.com.
  3. Name the file apple-app-site-association with no extension.
  4. Allow all IPs, regions and user agents on /.well-known/ in your WAF, CDN and bot settings.
  5. Use a valid, trusted certificate.
  6. Reinstall the app on a test device, or wait for the CDN to refetch. Apple says it requests the file within 24 hours.

An nginx example that serves the file without rewrites:

location = /.well-known/apple-app-site-association {
    default_type application/json;
    try_files /.well-known/apple-app-site-association =404;
}

The Android equivalent is covered in assetlinks redirect. Once the file is reachable, confirm its content with sudo swcutil verify, and if old rules linger, see AASA changes not picked up. Repeat curl -I https://example.com/.well-known/apple-app-site-association for each domain.

FAQ

Common questions

Does Apple follow a redirect from example.com to www.example.com?

No. Apple's technote says redirects on the file are not supported. Serve the file with a 200 on each host listed in the entitlement.

My server blocks bots. What should I allow?

Apple asks for the file to be reachable from any IP, any region and any user agent. Exempt the `/.well-known/` path from bot and geo rules rather than trying to allowlist specific fetchers.

Is a self-signed certificate acceptable?

Not for production. Apple requires a valid certificate; only developer mode, used with development-signed apps on opted-in devices, accepts untrusted certificates.

Do I still need the file at the root of the domain?

Current Apple documentation only describes the `/.well-known/` location. Apple's archived Handoff guide mentions a fallback to the root, but whether the current CDN still uses it is not documented, so host it in `/.well-known/`.

What are UTM parameters?

UTM parameters are tags added to the end of a link, such as utm_source and utm_campaign, that tell analytics tools where a visit came from. They let you see which campaign, channel and ad brought each visitor.

Which UTM parameters are required?

Use utm_source, utm_medium and utm_campaign on every campaign link. utm_term and utm_content are optional and help you compare keywords or ad variants.