Deep Link Doctor
Home / Developer notes

AASA file is not valid JSON

Your apple-app-site-association file has a JSON syntax error, so universal links never open the app. How to find the broken line and fix it in minutes.

SymptomUniversal links never open the app on any device and every link loads the website instead.
Likely causeThe apple-app-site-association file contains a syntax error, so it cannot be parsed as JSON.
FixFind the error with a JSON parser such as jq, correct it, then serve the corrected file with a 200 response.

Short answer: A single syntax error, such as a trailing comma or a missing quote, makes the whole apple-app-site-association (AASA) file unreadable. iOS then has no rules for your domain and opens every link in the browser. Run the file through a JSON parser such as jq to see the exact line and column.

What is happening

Invalid AASA JSON: an apple-app-site-association file that a JSON parser rejects, which leaves iOS with no universal link rules for the domain.

The file is either read in full or not at all. There is no partial parsing, so a typo on line 40 disables the rules on line 2 as well. Apple's debugging technote (TN3155) lists invalid JSON as one of the reasons links never open the app.

  • Every universal link on the domain falls back to Safari.
  • The long-press menu in Notes shows no "Open in app" option.
  • Nothing in the app crashes or logs an error, which makes this easy to miss.

Why does this happen?

Most invalid files are hand-edited, and JSON is stricter than JavaScript or most config formats. Common culprits are trailing commas, single quotes, comments, smart quotes pasted from a document, and an HTML error page served in place of the file.

  • Trailing comma: a comma after the last item in an array or object.
  • Comments: JSON has no comment syntax. Apple's format has a comment key for notes instead.
  • Smart quotes: curly quotes copied from a word processor or chat tool.
  • Wrong body: a server or CDN returning an HTML page (for example a login or error page) at the AASA URL.
  • Mixed formats: Apple warns that mixing the legacy paths format with components "may result in unexpected behavior", even when the JSON itself parses.

How to confirm it

  1. Fetch the live file exactly as Apple would: curl -v https://example.com/.well-known/apple-app-site-association.
  2. Check the body starts with { and is not HTML.
  3. Run the body through a JSON parser, for example curl -s https://example.com/.well-known/apple-app-site-association | jq .. It reports the line and column of the first syntax error.
  4. On a Mac, run sudo swcutil dl -d example.com to confirm the file downloads, then sudo swcutil verify -d example.com -j apple-app-site-association -u https://example.com/your/path to test a URL against it.
  5. Optionally, compare against the copy on Apple's CDN with curl -i https://app-site-association.cdn-apple.com/a/v1/example.com. This URL is widely used for debugging but is not on an Apple documentation page.

How to fix it

  1. Correct the syntax error the parser reports, then parse again until the file is clean.
  2. Replace any comments with "comment" keys inside components entries.
  3. Use one format only: appIDs plus components for current iOS versions.
  4. Deploy the file to /.well-known/apple-app-site-association, served over HTTPS with a 200 and no redirect.
  5. Reinstall the app on a test device. Apple says devices download the file when the app is installed and check for updates roughly once a week after that.

A minimal valid file looks like this:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/help/website/*", "exclude": true, "comment": "Keep on the web" },
          { "/": "/buy/*" }
        ]
      }
    ]
  }
}

If you would rather not hand-write JSON, start from the example in the universal links setup guide, and for the next likely problem after a syntax fix, see wrong app ID.

FAQ

Common questions

Does one syntax error really disable every universal link?

Yes. The file has to parse before iOS can read any rule in it, so a single error leaves the domain with no rules. Every link on that domain then opens in the browser.

Can I add comments to an apple-app-site-association file?

Not with `//` or `/* */`, because JSON has no comment syntax. Apple's `components` format includes a `comment` key that the system ignores, so put notes there instead.

Why does the file look fine in my browser but fail to parse?

Your browser may be showing a cached or logged-in version, while Apple's CDN sees something else, such as an HTML error page. Fetch it with curl from outside your network and check the raw body.

How long after fixing the file will links work?

Apple's CDN requests the file within 24 hours, and devices check roughly once a week after install. Reinstalling the app on a test device pulls a fresh copy from the CDN, and developer mode bypasses the CDN entirely while testing.

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.