# assetlinks.json Errors & How to Fix Them

> Fix assetlinks.json errors: wrong SHA-256 fingerprint, Play App Signing, package name mismatch, hosting issues, and debug vs release certificates.

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

Complete guide to assetlinks.json errors, validation, and fixes. Learn about SHA-256 fingerprints, Play App Signing, package names, hosting, and multiple fingerprint configurations.

## Understanding assetlinks.json structure

### Minimal valid assetlinks.json

```json
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": ["AA:BB:CC:DD:..."]
    }
  }
]
```

### File Location & Hosting

Must be hosted at: `https://yourdomain.com/.well-known/assetlinks.json`

- **Content-Type:** application/json (not text/plain)
- **HTTP Status:** 200 OK (not 301, 302, or 404)
- **Accessibility:** Publicly accessible, no authentication required

### Key Fields Explained

- **relation:** Must be: "delegate_permission/common.handle_all_urls" for app links
- **namespace:** Must be: "android_app" for Android app links
- **package_name:** Your app's package name from AndroidManifest.xml (e.g., com.example.app)
- **sha256_cert_fingerprints:** Array of SHA-256 fingerprints in uppercase, colon-separated format

## Understanding SHA-256 fingerprints

### Critical distinction: Play App Signing vs Local Keystore

If you upload unsigned APKs to Google Play Console, Google re-signs your app with a different key. This creates a **different SHA-256 fingerprint** than your local keystore. Always use the Play Console fingerprint.

### How to get SHA-256 fingerprint

#### Option 1: Google Play Console (Recommended)

1. Go to Google Play Console
2. Select your app
3. Go to Release > Internal testing (or Production)
4. Look for "App signing for internal testing" or "Google Play App Signing"
5. Copy the SHA-256 certificate fingerprint
6. Format: AA:BB:CC:DD:... (uppercase, colon-separated)

#### Option 2: Using keytool (Local Testing Only)

Only if you self-sign and are not using Play App Signing:

```bash
keytool -list -v -keystore keystore.jks | grep SHA256
```

### SHA-256 Format Requirements

- **Uppercase:** AA:BB:CC (not aa:bb:cc)
- **Colon-separated:** AA:BB:CC:DD (not AABBCCDD)
- **No spaces:** AA:BB (not AA: BB)
- **In array:** ["AA:BB:CC:..."] with square brackets

### Multiple Fingerprints

You can add multiple fingerprints if your app is signed with different keys:

```json
"sha256_cert_fingerprints": [
  "AA:BB:CC:DD:EE:FF:...", // Release key
  "11:22:33:44:55:66:...", // Debug key
  "AA:AA:AA:AA:AA:AA:..."  // Other signing key
]
```

Useful for supporting both debug and release builds, or multiple developer keys.

## Common assetlinks.json errors and fixes

### SHA-256 fingerprint does not match

**Cause:** Using local keytool fingerprint when Play App Signing is enabled in Google Play Console

**Fix:** Get SHA-256 from Google Play Console > App signing section, not from keytool

### assetlinks.json not found (404)

**Cause:** File is not at /.well-known/assetlinks.json or web server not configured

**Fix:** Verify file location and test with curl. Ensure web server serves from correct root directory.

### Package name mismatch

**Cause:** package_name in assetlinks.json does not match AndroidManifest.xml

**Fix:** Verify package_name in assetlinks.json exactly matches `<manifest package="...">` in AndroidManifest.xml

### Content-Type is text/plain

**Cause:** Web server serving assetlinks.json as plain text instead of JSON

**Fix:** Configure web server to serve /.well-known/assetlinks.json with Content-Type: application/json

### Invalid JSON syntax

**Cause:** Trailing commas, missing quotes, or mismatched brackets

**Fix:** Use /assetlinks-validator to check JSON syntax. Remove trailing commas, ensure all keys are quoted.

### SHA-256 has lowercase letters

**Cause:** Fingerprint formatted in lowercase instead of uppercase

**Fix:** Convert all SHA-256 characters to uppercase: aa:bb:cc → AA:BB:CC

### SHA-256 has spaces

**Cause:** Fingerprint contains spaces instead of being compact

**Fix:** Remove all spaces: AA: BB: CC → AA:BB:CC

### Wrong relation type

**Cause:** relation field set to something other than delegate_permission/common.handle_all_urls

**Fix:** Use exactly: `"relation": ["delegate_permission/common.handle_all_urls"]`

### CDN caching assetlinks.json

**Cause:** Changes to assetlinks.json not reflected because CDN is caching old version

**Fix:** Purge CDN cache or test with curl. Disable caching for /.well-known/ paths during development.

### App signed with different key than assetlinks.json

**Cause:** App APK signed with key A, but assetlinks.json has fingerprint from key B

**Fix:** Ensure APK is signed with the same key whose fingerprint is in assetlinks.json

## Quick validation with Redirectly

Paste your assetlinks.json and get instant validation with detailed error messages:

- [Open assetlinks Validator](https://redirectly.app/assetlinks-validator.md)

## Frequently asked questions

### I have both debug and release builds. What SHA-256 do I use?

Add both to the sha256_cert_fingerprints array. This way both debug and release builds can use app links. Use the release fingerprint for production app links.

### Where do I get my package name?

Open AndroidManifest.xml and look for: `<manifest package="com.example.app">`. The package_name in assetlinks.json must match exactly, including capitalization.

### How long does assetlinks.json verification take?

Google Play Console usually verifies within minutes, but can take up to 2 hours. After verification, app links work automatically when app installs from Play Store.

### Can I test assetlinks.json locally before deploying?

Yes. Use your local keytool SHA-256 for testing, then swap to the Play Console fingerprint before publishing. Or test on internal testing track in Play Console.

### What if my SHA-256 fingerprint changed?

If you changed signing keys, update the sha256_cert_fingerprints array with the new fingerprint. Old fingerprint will stop working. Keep old fingerprints if you need to support old app versions.

---

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