/ 01TOOLFREE TOOLS · FOR DEVELOPERS

AASA validator

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.

The domain your links use. A full URL works too; we keep only the host. The result has its own URL you can share.

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:

Terminal
curl -i https://app-site-association.cdn-apple.com/a/v1/example.com

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 fetched Broken

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.

Terminal
curl -sv https://example.com/.well-known/apple-app-site-association -o /dev/null

The file is behind a redirect Broken

ios.redirect

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 200 Broken

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.

Terminal
curl -i https://example.com/.well-known/apple-app-site-association

A Strait link domain with no iPhone app yet Broken

ios.not_set_up

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.

Terminal
curl -i https://<your-handle>.strait.link/.well-known/apple-app-site-association

Content-Type is not application/json Degraded

ios.content_type

The file has no extension, so many servers send application/octet-stream or text/plain. Apple expects application/json.

Fix: Set the Content-Type for this exact 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;
}

The file is larger than 128 KB Broken

ios.size

Apple ignores association files over 128 KB uncompressed. Large files usually list every path one by one.

Fix: Replace long path lists with wildcards or components rules.

Example
"components": [{ "/": "/products/*" }]

The file is signed (CMS/PKCS#7) Broken

ios.signed

Signed association files were only needed before iOS 9. Current iOS expects plain, unsigned JSON.

Fix: Publish the plain JSON file instead.

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

Gzip data without a Content-Encoding header Broken

ios.gzip

The body is gzip-compressed but the server did not say so, so the file cannot be read as JSON.

Fix: Serve the file uncompressed, or send Content-Encoding: gzip with it.

Not valid JSON Broken

ios.json

The body could not be parsed: a trailing comma, a comment, or an HTML page in place of the file. iOS ignores it.

Fix: Validate the file and fix the syntax error. Do not add .json to the URL.

Terminal
python3 -m json.tool apple-app-site-association

The file starts with a byte-order mark Degraded

ios.bom

An invisible UTF-8 BOM comes before the JSON. Some parsers reject it.

Fix: Save the file as UTF-8 without BOM.

Terminal
sed -i '1s/^\xEF\xBB\xBF//' apple-app-site-association

The file must be a JSON object Broken

ios.shape

The file is an object with keys such as applinks and webcredentials, not an array.

Fix: Use the object format.

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

"applinks.apps" should be an empty list Degraded

ios.apps_key

This legacy key must be [] when present. iOS 13 and later ignore it.

Fix: Set it to [] or remove it.

Example
"apps": []

"applinks.details" is missing or empty Broken

ios.details

details lists which apps may open which paths. Without it, no app opens links.

Fix: Add at least one entry with appIDs and components.

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

A details entry is not an object Broken

ios.detail

Each entry in details is an object with appIDs and components (or the older appID and paths).

Fix: Use one object per group of apps.

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

A details entry names no app Broken

ios.detail_ids

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 ID Broken

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 placeholder Degraded

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 components Broken

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 matches Broken

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 list Broken

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 keys Degraded

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.

Fix: Use only the documented keys.

Example
{ "/": "/products/*", "?": { "ref": "*" }, "exclude": false }

A "/" pattern looks wrong Degraded

ios.component_path

The "/" value should be a path pattern starting with / or *.

Fix: Use a pattern like /products/*.

Example
{ "/": "/products/*" }

"?" must be a string or an object Broken

ios.component_query

Query matching takes a pattern string, or an object of parameter name → pattern.

Fix: Use an object for named parameters.

Example
{ "/": "/s/*", "?": { "ref": "*" } }

"#" must be a string Broken

ios.component_fragment

Fragment matching takes a pattern string.

Fix: Use a string pattern.

Example
{ "#": "section-*" }

"exclude" must be true or false Broken

ios.component_exclude

exclude is a JSON boolean. "true" in quotes is a string and is not read as an exclusion.

Fix: Remove the quotes.

Example
{ "/": "/admin/*", "exclude": true }

"webcredentials" is malformed Degraded

ios.webcredentials

webcredentials (optional, for password autofill) must be { "apps": ["TEAMID.bundle.id"] }.

Fix: Fix the format or remove the section.

Example
"webcredentials": { "apps": ["ABCDE12345.com.example.shop"] }

The file is only at the old root location Degraded

ios.legacy_only

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 links OK

ios.apps

The app IDs this domain lets open its links as Universal Links.

apple-app-site-association looks correct OK

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>.

Terminal
curl -i https://app-site-association.cdn-apple.com/a/v1/example.com

Questions

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.

Start free