Deep Link Doctor
Home / Developer notes

AASA file is larger than 128 KB

Apple's archived docs cap the apple-app-site-association file at 128 KB uncompressed. Why large AASA files fail and how to shrink yours with wildcards.

SymptomUniversal links stop working after the apple-app-site-association file grows past a certain size.
Likely causeApple's archived documentation sets a 128 KB uncompressed limit for the file, and a long list of paths can exceed it.
FixReplace long lists of individual paths with wildcard patterns or components so the file stays under 128 KB.

Short answer: Apple's archived documentation says the apple-app-site-association file must be no larger than 128 KB uncompressed. Files that list thousands of individual URLs can pass that limit. Replace the list with a few wildcard rules and the file usually drops to a few hundred bytes.

What is happening

AASA size limit: the 128 KB uncompressed ceiling for the apple-app-site-association file, introduced for apps on iOS 9.3.1 and later according to Apple's archived Handoff guide.

The limit applies to the uncompressed file, so gzip on your server does not help. Apple added the limit in April 2016 and it appears in the archived Handoff and App Search guides. Current Apple pages do not restate it, but it is still widely cited, and staying under it costs nothing.

  • curl -I https://example.com/.well-known/apple-app-site-association shows a Content-Length above 128 KB (if the server reports it uncompressed), or the downloaded file is larger than 128 KB on disk.
  • A file listing every product or article URL individually is the usual cause.
  • Signing the file does not change the limit: the archived text says it applies "regardless of whether the file is signed".

Why does this happen?

The file grows because someone generates it from a sitemap or database, adding one rule per page. Wildcards were designed to avoid this.

  • Generated path lists: one paths or components entry per URL.
  • Many app IDs repeated: the same long rule list copied under several details entries.
  • Verbose comments: long comment strings on every rule add up.

How to confirm it

  1. Download the live file: curl -s https://example.com/.well-known/apple-app-site-association -o aasa.json.
  2. Check the uncompressed size: wc -c aasa.json. Anything above 131,072 bytes (128 KB) is over the limit.
  3. Download it with curl -o aasa.json and check the size on disk, which is the uncompressed size.

How to fix it

  1. Group URLs by their path prefix, for example /product/, /article/ or /u/.
  2. Replace each group with one wildcard rule. * matches zero or more characters, ? matches one character and ?* matches one or more.
  3. Put exclusions first. Apple says "the first match wins", so an exclude rule must sit above the broader rule it carves out.
  4. Use a single details entry with an appIDs array when several apps share the same rules, rather than repeating the rules per app.
  5. Shorten or remove comment values.
  6. Deploy, then reinstall the app on a test device to pick up the new file.

A file that covers thousands of product pages in three rules:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app", "ABCDE12345.com.example.app2"],
        "components": [
          { "/": "/product/*/reviews", "exclude": true },
          { "/": "/product/*" },
          { "/": "/article/*" }
        ]
      }
    ]
  }
}

Compact files like this, with exclusions listed first, are easier to keep small. If some URLs then stop matching, see path not matched.

FAQ

Common questions

Is the 128 KB limit still enforced?

Apple's current documentation pages do not restate it, so this cannot be confirmed from a current source. The limit is documented in Apple's archived guides for iOS 9.3.1 and later, and keeping the file small is the safe choice.

Does gzip compression count towards the 128 KB?

No. The archived text specifies the uncompressed size, so a file that is 40 KB over the wire can still be over the limit once decompressed.

How small should a typical AASA file be?

Most apps need a handful of rules, so a few hundred bytes to a few kilobytes is normal. If your file is tens of kilobytes, it almost certainly lists individual URLs that wildcards could cover.

Can I split rules across several files?

Not on the same domain, because each domain serves one file at `/.well-known/apple-app-site-association`. Each subdomain does serve its own file, so rules for `shop.example.com` live in that subdomain's file.

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.