Validate the apple-app-site-association file that lets iPhone links open your app: reachability, redirects, size, app IDs, components and paths, each problem with a fix. No account needed.
How Universal Links get verified
Your app declares applinks:your-domain in its Associated Domains entitlement. When the app is installed, iOS asks Apple's CDN for that domain's apple-app-site-association file, which the CDN fetched from https://your-domain/.well-known/apple-app-site-association. If the file names your app ID (Team ID plus bundle ID) and a component matches the tapped URL, iOS opens the app instead of Safari.
Apple fetches the file without following redirects and ignores files over 128 KB. A signed file, a gzip body without the right header, or JSON with a trailing comma all make the whole domain fall back to Safari.
Check Apple's copy too
This validator reads the file from your server, which is what Apple's CDN copies. To see what phones get right now, ask the CDN directly:
During development you can skip the CDN by adding ?mode=developer to the entitlement (applinks:example.com?mode=developer) and turning on Associated Domains Development in the iPhone's Developer settings. If your links run on a Strait link domain, Strait serves this file from your app settings; iPhone links on Strait are live, tested on a real iPhone. To write a file from scratch, use the AASA generator. To see which rule decides one particular link, paste it into the deep link tester.
Every rule this checker reports
Each finding in a result links here. The id in grey (for example ios.redirect) is what the copied report shows. Rules found only at the old root location keep the same id. Checking Android links too? See the assetlinks.json checker.
The file could not be fetchedBroken
ios.fetch
The checker could not download the file: DNS, TLS, a timeout or a private address. Apple's CDN would fail in the same way.
Fix: Make the URL load over https with a valid certificate, from the public internet, without a login or a bot challenge.
Apple requires the file to be served directly with a 200. A redirect (apex to www, http to https inside the path, a trailing slash) makes the domain unverified.
Fix: Serve the file at exactly this URL on every host your links use.
nginx
# nginx: serve the file directly, as JSON, with no redirect
location = /.well-known/apple-app-site-association {
default_type application/json;
try_files $uri =404;
}
The server did not answer 200Broken
ios.status
A 404 means no file at /.well-known/apple-app-site-association. A 403 is often a CDN bot rule blocking Apple's fetcher.
Fix: Publish the file (no .json extension) and allow anonymous requests to it.
Strait serves this file for you on your link domain, but only once Dashboard → Apps & stores has your iPhone app. Until then the domain answers 404 "not configured".
Fix: Fill in Dashboard → Apps & stores (Team ID and bundle ID), wait a minute, then check again. Already done? Make sure the domain is your link domain from Dashboard → Setup → Your keys.
Each entry needs appIDs (a list, iOS 13+) or appID (a string, the older format).
Fix: Add appIDs with your Team ID and bundle ID.
Example
"appIDs": ["ABCDE12345.com.example.shop"]
Invalid app IDBroken
ios.appid
An app ID is your 10-character Team ID, a dot, then the bundle ID (ABCDE12345.com.example.shop). The Team ID part is uppercase letters and digits.
Fix: Copy the Team ID from developer.apple.com → Membership and the bundle ID from Xcode → Signing & Capabilities.
Example
"appIDs": ["ABCDE12345.com.example.shop"]
An app ID looks like a placeholderDegraded
ios.placeholder
The app ID looks like an example value (TEAMID, ABCDE12345, com.example), so no real app will match it.
Fix: Replace it with your real Team ID and bundle ID.
An entry has no paths or componentsBroken
ios.detail_rules
Without components (iOS 13+) or paths (older), the entry matches no URL.
Fix: Add components. { "/": "*" } matches every path.
Example
"components": [{ "/": "*" }]
"paths" is malformed or never matchesBroken
ios.paths
paths is a list of strings such as "/products/*" or "NOT /admin/*". A URL path always starts with /, so a pattern (after an optional "NOT ") that starts with anything other than /, * or ? can never match.
Fix: Fix the patterns, or move to components, which iOS 13 and later prefer.
Example
"paths": ["/products/*", "NOT /admin/*"]
"components" must be a listBroken
ios.components
components is an array of objects, one per rule.
Fix: Make it an array.
Example
"components": [{ "/": "/products/*" }]
A component is malformed or has unknown keysDegraded
ios.component
Each component is an object with keys "/", "?", "#", "exclude", "comment", "caseSensitive" or "percentEncoded". iOS ignores other keys, so the rule may match more or less than you expect.
The file exists at /apple-app-site-association but not at /.well-known/apple-app-site-association. Apple looks in /.well-known/ first; the root location is a legacy fallback.
Fix: Serve the same file at the /.well-known/ path.
nginx
# nginx: serve the file directly, as JSON, with no redirect
location = /.well-known/apple-app-site-association {
default_type application/json;
try_files $uri =404;
}
Apps allowed to open linksOK
ios.apps
The app IDs this domain lets open its links as Universal Links.
apple-app-site-association looks correctOK
ios.valid
Served over https with a 200, no redirect, valid JSON and well-formed rules. iPhones read the file through Apple's CDN, which caches it, so a fix can take a while to reach phones. Apple's CDN copy is at app-site-association.cdn-apple.com/a/v1/<your domain>.
I fixed the file. Why do iPhones still open Safari?
iPhones do not read your server directly. They read a copy from Apple's CDN, which refreshes on its own schedule, and a phone re-checks when the app is installed or updated. Check what Apple's CDN currently holds at app-site-association.cdn-apple.com/a/v1/your-domain, then reinstall the app to test.
Do I need the .json extension?
No. The file is called apple-app-site-association with no extension, served at /.well-known/apple-app-site-association with Content-Type application/json.
components or paths?
components is the format for iOS 13 and later and supports query and fragment matching and exclusions. paths is the older format. You can keep both in the same entry while you still support older iOS versions.
Why does a link typed into Safari's address bar not open my app?
Universal Links open the app when someone taps a link in another app or page. Typing or pasting the address into Safari, or tapping a link to the same domain you are already on, keeps you in Safari by design.
Is this checker's result the same as what an iPhone sees?
It checks the file your domain serves. Apple's CDN may still hold an older copy, and the app needs the Associated Domains entitlement (applinks:your-domain) for the file to matter. The rule notes below cover both.
One link for iPhone, Android and the web
Strait hosts the association files on your link domain, routes each tap to the app, the store or the web, and shows you what happened.