{"id":2029,"date":"2026-08-14T13:00:00","date_gmt":"2026-08-14T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=2029"},"modified":"2026-03-07T03:50:27","modified_gmt":"2026-03-07T08:50:27","slug":"debugging-aasa-file","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/debugging-aasa-file\/","title":{"rendered":"Debugging AASA File Issues: Troubleshooting Guide"},"content":{"rendered":"\n

When Universal Links stop working, the Apple App Site Association (AASA) file is the most common culprit. The AASA file tells iOS which URL paths your app handles, and any error in its format, hosting, or content will silently break deep linking. This guide walks through systematic debugging of AASA issues.<\/p>\n\n\n\n

For AASA file setup, see AASA file setup<\/a>. For comprehensive Universal Links coverage, see universal links: everything you need to know<\/a>. For iOS troubleshooting, see the iOS troubleshooting guide<\/a>.<\/p>\n\n\n\n

Quick Diagnostic Checklist<\/h2>\n\n\n\n

Before diving into detailed debugging, check these common issues:<\/p>\n\n\n\n

\n\n\n\n\n\n\n\n\n\n
Check<\/th>\nCommand\/Action<\/th>\nExpected Result<\/th>\n<\/tr>\n<\/thead>\n
AASA file is accessible<\/td>\ncurl -I https:\/\/yourdomain.com\/.well-known\/apple-app-site-association<\/code><\/td>\nHTTP 200, Content-Type: application\/json<\/td>\n<\/tr>\n
Valid JSON<\/td>\nPaste file content into jsonlint.com<\/a><\/td>\n"Valid JSON"<\/td>\n<\/tr>\n
Correct Team ID<\/td>\nCheck in Apple Developer Portal<\/a><\/td>\nMatches your appID<\/code> prefix<\/td>\n<\/tr>\n
Correct Bundle ID<\/td>\nCheck in Xcode project settings<\/td>\nMatches your appID<\/code> suffix<\/td>\n<\/tr>\n
Associated Domains entitlement<\/td>\nXcode \u2192 Signing & Capabilities<\/td>\napplinks:yourdomain.com<\/code> present<\/td>\n<\/tr>\n
HTTPS with valid certificate<\/td>\nBrowser shows lock icon on domain<\/td>\nNo certificate errors<\/td>\n<\/tr>\n
No redirects to AASA file<\/td>\ncurl -v https:\/\/yourdomain.com\/.well-known\/apple-app-site-association<\/code><\/td>\nDirect 200, no 301\/302<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n

Step 1: Verify the AASA File Is Accessible<\/h2>\n\n\n\n

Check with curl<\/h3>\n\n\n\n
curl -v https:\/\/yourdomain.com\/.well-known\/apple-app-site-association\n<\/code><\/pre>\n\n\n\n
What to look for:<\/p>\n\n\n\n
\n\n\n\n\n\n\n\n
Response<\/th>\nMeaning<\/th>\nFix<\/th>\n<\/tr>\n<\/thead>\n
HTTP 200 with JSON<\/td>\nFile is accessible<\/td>\nContinue to Step 2<\/td>\n<\/tr>\n
HTTP 404<\/td>\nFile not found<\/td>\nPlace the file at \/.well-known\/apple-app-site-association<\/code><\/td>\n<\/tr>\n
HTTP 301\/302 redirect<\/td>\nRedirect present<\/td>\nRemove the redirect; Apple does not follow redirects for AASA<\/td>\n<\/tr>\n
HTTP 403<\/td>\nAccess denied<\/td>\nCheck server permissions, WAF rules, or authentication<\/td>\n<\/tr>\n
Connection error<\/td>\nServer unreachable<\/td>\nCheck DNS, firewall, and SSL configuration<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
Common Hosting Issues<\/h3>\n\n\n\n
Nginx<\/strong>: Ensure the \/.well-known\/<\/code> directory is served:<\/p>\n\n\n\n
location \/.well-known\/apple-app-site-association {\n    default_type application\/json;\n}\n<\/code><\/pre>\n\n\n\n
Apache<\/strong>: Add a MIME type handler:<\/p>\n\n\n\n
<Files "apple-app-site-association">\n    Header set Content-Type "application\/json"\n<\/Files>\n<\/code><\/pre>\n\n\n\n
Cloudflare\/CDN<\/strong>: Ensure your CDN is not blocking the file. Some WAF rules block files without extensions. Add an exception for the AASA path.<\/p>\n\n\n\n
S3\/Static hosting<\/strong>: Set the Content-Type<\/code> metadata to application\/json<\/code> on the file.<\/p>\n\n\n\n
Step 2: Validate the JSON<\/h2>\n\n\n\n
Common JSON Errors<\/h3>\n\n\n\n
\n\n\n\n\n\n\n\n
Error<\/th>\nExample<\/th>\nFix<\/th>\n<\/tr>\n<\/thead>\n
Trailing comma<\/td>\n"paths": ["\/product\/*",]<\/code><\/td>\nRemove the trailing comma<\/td>\n<\/tr>\n
Missing quotes<\/td>\n{appID: "ABC123.com.app"}<\/code><\/td>\nAdd quotes around keys<\/td>\n<\/tr>\n
Wrong encoding<\/td>\nBOM or non-UTF-8 characters<\/td>\nSave as UTF-8 without BOM<\/td>\n<\/tr>\n
Comments<\/td>\n\/\/ This is a comment<\/code><\/td>\nRemove all comments (JSON does not support them)<\/td>\n<\/tr>\n
Single quotes<\/td>\n{'appID': 'ABC123'}<\/code><\/td>\nUse double quotes<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
AASA v1 vs v2 Format<\/h3>\n\n\n\n
iOS 13+ supports the v2 AASA format. iOS 12 and earlier require v1:<\/p>\n\n\n\n
v2 (recommended, Apple documentation<\/a>)<\/strong>:<\/p>\n\n\n\n
{\n  "applinks": {\n    "details": [\n      {\n        "appIDs": ["TEAMID.com.yourcompany.app"],\n        "components": [\n          { "\/": "\/product\/*", "comment": "Product pages" },\n          { "\/": "\/category\/*", "comment": "Category pages" }\n        ]\n      }\n    ]\n  }\n}\n<\/code><\/pre>\n\n\n\n
v1 (legacy)<\/strong>:<\/p>\n\n\n\n
{\n  "applinks": {\n    "apps": [],\n    "details": [\n      {\n        "appID": "TEAMID.com.yourcompany.app",\n        "paths": ["\/product\/*", "\/category\/*"]\n      }\n    ]\n  }\n}\n<\/code><\/pre>\n\n\n\n
If you need to support iOS 12 and earlier, include both formats. iOS will use the v2 format if present.<\/p>\n\n\n\n
Step 3: Verify App ID Configuration<\/h2>\n\n\n\n
The appID<\/code> in the AASA file must exactly match your Apple Developer configuration:<\/p>\n\n\n\n
Format: <Team ID>.<Bundle ID>\nExample: A1B2C3D4E5.com.yourcompany.yourapp\n<\/code><\/pre>\n\n\n\n
Finding Your Team ID<\/h3>\n\n\n\n
    \n
  1. Go to Apple Developer Portal<\/a>.<\/li>\n
  2. Click "Membership Details."<\/li>\n
  3. Your Team ID is a 10-character alphanumeric string (e.g., A1B2C3D4E5<\/code>).<\/li>\n<\/ol>\n\n\n\n
    Finding Your Bundle ID<\/h3>\n\n\n\n
      \n
    1. Open your Xcode project.<\/li>\n
    2. Select your app target.<\/li>\n
    3. Go to the "General" tab.<\/li>\n
    4. The "Bundle Identifier" field shows your Bundle ID (e.g., com.yourcompany.yourapp<\/code>).<\/li>\n<\/ol>\n\n\n\n
      Common Mistakes<\/h3>\n\n\n\n
      \n\n\n\n\n\n\n
      Mistake<\/th>\nExample<\/th>\nFix<\/th>\n<\/tr>\n<\/thead>\n
      Wrong Team ID<\/td>\nUsing a different team's ID<\/td>\nVerify in Apple Developer Portal<\/td>\n<\/tr>\n
      Bundle ID mismatch<\/td>\ncom.yourcompany.App<\/code> vs com.yourcompany.app<\/code> (case sensitive)<\/td>\nBundle IDs are case sensitive<\/td>\n<\/tr>\n
      Missing Team ID prefix<\/td>\ncom.yourcompany.app<\/code> instead of A1B2C3D4E5.com.yourcompany.app<\/code><\/td>\nAlways include the Team ID<\/td>\n<\/tr>\n
      Using wildcard Bundle ID<\/td>\nA1B2C3D4E5.*<\/code><\/td>\nUse the explicit Bundle ID<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
      Step 4: Check the Associated Domains Entitlement<\/h2>\n\n\n\n
      In Xcode:<\/p>\n\n\n\n
        \n
      1. Select your app target.<\/li>\n
      2. Go to "Signing & Capabilities."<\/li>\n
      3. Check for the "Associated Domains" capability.<\/li>\n
      4. Verify the domain entry: applinks:yourdomain.com<\/code><\/li>\n<\/ol>\n\n\n\n
        Common Entitlement Issues<\/h3>\n\n\n\n
        \n\n\n\n\n\n\n\n
        Issue<\/th>\nSymptom<\/th>\nFix<\/th>\n<\/tr>\n<\/thead>\n
        Missing entitlement<\/td>\nUniversal Links never trigger<\/td>\nAdd Associated Domains capability<\/td>\n<\/tr>\n
        Wrong domain<\/td>\nLinks from your domain open in Safari<\/td>\nVerify the domain matches exactly<\/td>\n<\/tr>\n
        https:\/\/<\/code> prefix in domain<\/td>\nEntitlement is invalid<\/td>\nUse just the domain: applinks:yourdomain.com<\/code> (no protocol)<\/td>\n<\/tr>\n
        Missing subdomain<\/td>\nwww.yourdomain.com<\/code> links do not work<\/td>\nAdd both applinks:yourdomain.com<\/code> and applinks:www.yourdomain.com<\/code><\/td>\n<\/tr>\n
        Development mode<\/td>\nWorks in development but not production<\/td>\nRemove ?mode=developer<\/code> suffix for production<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
        Step 5: Test Path Matching<\/h2>\n\n\n\n
        Even if the AASA file is valid, your paths may not match the URLs you are testing:<\/p>\n\n\n\n
        v2 Component Matching<\/h3>\n\n\n\n
        {\n  "components": [\n    { "\/": "\/product\/*" },\n    { "\/": "\/category\/*\/items" },\n    { "\/": "\/sale", "?": { "promo": "?*" } }\n  ]\n}\n<\/code><\/pre>\n\n\n\n
        \n\n\n\n\n\n\n\n\n\n
        URL<\/th>\nPattern<\/th>\nMatches?<\/th>\n<\/tr>\n<\/thead>\n
        \/product\/shoes<\/code><\/td>\n\/product\/*<\/code><\/td>\nYes<\/td>\n<\/tr>\n
        \/product\/shoes\/red<\/code><\/td>\n\/product\/*<\/code><\/td>\nYes (*<\/code> matches entire remainder)<\/td>\n<\/tr>\n
        \/products\/shoes<\/code><\/td>\n\/product\/*<\/code><\/td>\nNo (note the s<\/code>)<\/td>\n<\/tr>\n
        \/category\/mens\/items<\/code><\/td>\n\/category\/*\/items<\/code><\/td>\nYes<\/td>\n<\/tr>\n
        \/category\/mens<\/code><\/td>\n\/category\/*\/items<\/code><\/td>\nNo (missing \/items<\/code>)<\/td>\n<\/tr>\n
        \/sale?promo=summer<\/code><\/td>\n\/sale<\/code> with promo<\/code> query<\/td>\nYes<\/td>\n<\/tr>\n
        \/sale<\/code><\/td>\n\/sale<\/code> with promo<\/code> query<\/td>\nNo (missing required query param)<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n
        Exclusion Patterns<\/h3>\n\n\n\n
        Exclude paths you do not want the app to handle:<\/p>\n\n\n\n
        {\n  "components": [\n    { "\/": "\/product\/*" },\n    { "\/": "\/product\/*\/reviews", "exclude": true }\n  ]\n}\n<\/code><\/pre>\n\n\n\n
        The \/product\/shoes<\/code> link opens the app, but \/product\/shoes\/reviews<\/code> opens in Safari.<\/p>\n\n\n\n
        For advanced path matching, see AASA wildcards and path matching<\/a>.<\/p>\n\n\n\n
        Step 6: Apple's CDN Cache<\/h2>\n\n\n\n
        Apple caches AASA files on its own CDN. After updating your AASA file, changes may take 24-48 hours to propagate.<\/p>\n\n\n\n
        Check Apple's Cached Version<\/h3>\n\n\n\n
        curl -v https:\/\/app-site-association.cdn-apple.com\/a\/v1\/yourdomain.com\n<\/code><\/pre>\n\n\n\n
        If this returns an outdated version of your file, Apple's CDN has not refreshed yet.<\/p>\n\n\n\n
        Forcing a Refresh<\/h3>\n\n\n\n
        You cannot force Apple's CDN to refresh. However:<\/p>\n\n\n\n