What are the most common AASA file errors?

Invalid JSON syntax, wrong content-type header, incorrect team ID or bundle ID format, missing applinks key, and CDN/redirect chain issues.

How do I validate my AASA file?

Use the Redirectly AASA validator tool to check JSON syntax, content-type, bundle ID format, and applinks key presence.

What is the difference between team ID and bundle ID?

Team ID is your Apple Developer account identifier. Bundle ID is your app identifier. AASA file needs both in format: Team-ID.Bundle-ID

Why is content-type important for AASA files?

Apple requires AASA to be served with Content-Type: application/json. If served as text/plain, Apple will not recognize it.

Can AASA files use wildcard domains?

Yes, but carefully. Wildcard patterns like *.domain.com are supported, but be specific about which subdomains you want to support.

AASA File Errors & How to Fix Them | Redirectly

Basics

Understanding AASA file structure

Minimal valid AASA file

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM-ID.com.example.app",
        "paths": ["/path/*"]
      }
    ]
  }
}

appID Format

The appID must be: TEAM-ID.BUNDLE-ID

TEAM-ID: Found in Apple Developer Portal (10-character identifier)
BUNDLE-ID: Your app's bundle identifier from Xcode (e.g., com.example.app)
Example: 9ABC12345D.com.example.app

Paths Configuration

Specify which URL paths should trigger your app:

/path/* - Matches any URL starting with /path/
/* - Matches all paths on the domain
/path/to/page - Matches exact path only
NOT paths: ["/path/*"] - Excludes specific paths

Hosting Location

AASA file must be hosted at: https://yourdomain.com/.well-known/apple-app-site-association

No file extension. Must be served with Content-Type: application/json

Common errors

Common AASA errors and how to fix them

Unexpected token } in JSON

Cause: Trailing comma in array or object

"details": [ { ... }, ] // Wrong!

Fix: Remove trailing commas before closing brackets and braces

Expected property name or '}'

Cause: Missing quotes around JSON keys

{ applinks: {} } // Should be "applinks"

Fix: Wrap all JSON keys in double quotes: "applinks"

Invalid appID format

Cause: Team ID or bundle ID incorrect or formatted wrong

"appID": "9ABC12345Dcom.example.app" // Missing dot!

Fix: Use format Team-ID.Bundle-ID (e.g., 9ABC12345D.com.example.app)

Content-Type is text/plain

Cause: Web server configured to serve AASA as text file

curl -I shows Content-Type: text/plain

Fix: Configure web server to serve with Content-Type: application/json. Use .htaccess for Apache or nginx config for nginx.

File not found (404)

Cause: AASA file path is wrong or file does not exist

File at /app/aasa or /apple-app-site-association

Fix: Place file at /.well-known/apple-app-site-association in web root. Test with curl or browser.

Missing "applinks" key

Cause: JSON structure missing top-level applinks object

{ "details": [] } // Missing applinks!

Fix: Wrap all content in "applinks" object with nested "details" array

Paths array is empty

Cause: No paths specified or paths configured wrong

"paths": [] // Will never match any links!

Fix: Add path patterns: "paths": ["/path/*"] or "paths": ["/*"]

Redirect chain too long

Cause: AASA location redirects more than 5 times

domain.com -> cdn1.com -> cdn2.com -> ... (6+ hops)

Fix: Host AASA directly at /.well-known/ or limit redirects to 5 maximum

Team ID doesn't match Apple Developer account

Cause: Using wrong team ID from different account

"appID": "1234567890.com.example.app" // Wrong team ID

Fix: Get correct Team ID from Apple Developer Portal > Account tab

Validation

How to validate your AASA file

Use Redirectly AASA Validator

Go to https://redirectly.app/aasa-validator
Paste your AASA file content into the text area
Click "Validate"
Review error messages and fix issues

Test in your browser

Open https://yourdomain.com/.well-known/apple-app-site-association
Should see JSON content, not 404 or error
Should return 200 OK status
Verify Content-Type is application/json in response headers

Check with curl command

Run: curl -I https://yourdomain.com/.well-known/apple-app-site-association
Look for: HTTP/2 200 or HTTP/1.1 200 OK
Look for: Content-Type: application/json
No 301/302 redirects should be present

Validate JSON syntax

Use online JSON validator (jsonlint.com)
Paste your AASA file content
Look for syntax errors reported
Fix any trailing commas, missing quotes, or bracket mismatches

Verify team ID and bundle ID

Go to Apple Developer Portal
Account > Membership > Team ID (10 chars)
Your app in Xcode > General > Bundle Identifier
Verify appID in AASA is: TEAM-ID.BUNDLE-ID

Quick validation with Redirectly

Paste your AASA file and get instant validation with detailed error messages:

Open AASA Validator→

FAQ

Frequently asked questions

Can I use .json file extension instead of no extension?

No. Apple requires the file to be at /.well-known/apple-app-site-association with no file extension. The content-type header tells Apple it's JSON.

Can I host AASA on a subdomain instead of root domain?

Yes. You can host AASA on a subdomain if your universal links point to that subdomain. Each domain needs its own AASA file.

Do I need different AASA files for different app versions?

No. One AASA file per domain works for all versions of your app. Apple caches it for 24 hours, so updates take time to propagate.

What happens if my AASA file is invalid?

iOS will fall back to Safari. Users will see the webpage instead of your app opening. This is why validation is critical.

Can I wildcard all subdomains with applinks?

Yes, use "paths": ["/*"] to match all paths on the domain. For subdomains, you can use specific subdomains or a single wildcard AASA file.

AASA File Errors & How to Fix Them