# AASA File Errors & How to Fix Them

> Fix common AASA file errors: invalid JSON, wrong content-type, CDN and redirect issues, wildcard patterns, missing applinks key, and team ID confusion.

- Canonical: https://redirectly.app/debug/aasa-file-errors
- Site: [Redirectly](https://redirectly.app) — deferred deep linking for Flutter & React Native

Complete guide to AASA file errors, validation, and fixes. Learn about JSON syntax, content-type headers, team ID and bundle ID configuration, wildcard patterns, and CDN issues.

## Understanding AASA file structure

### Minimal valid AASA file

```json
{
  "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 AASA errors and how to fix them

### Unexpected token } in JSON

**Cause:** Trailing comma in array or object

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

**Fix:** Remove trailing commas before closing brackets and braces

### Expected property name or '}'

**Cause:** Missing quotes around JSON keys

**Example:** `{ 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

**Example:** `"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

**Example:** `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

**Example:** `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

**Example:** `{ "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

**Example:** `"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

**Example:** `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

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

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

## How to validate your AASA file

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

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

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

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

### 5. 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](https://redirectly.app/aasa-validator.md)

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

---

Full site index for AI agents: https://redirectly.app/llms.txt