Unity Addressables Remote Catalog Hash Mismatch After CDN Purge - Cache-Busting and Build Path Fix

Direct answer: When Addressables reports a remote catalog hash mismatch after you purge a CDN, players are usually downloading a catalog JSON and a catalog hash file that no longer describe the same content, or bundles at the remote load path no longer match what the catalog references. Fix it by verifying the live URL pair with HTTP tooling, aligning RemoteBuildPath and RemoteLoadPath for every active profile, publishing catalog JSON, hash file, and bundles as one atomic release, purging after upload completes, then validating on a device with player-side Addressables cache cleared.

If your release logs show remote catalog hash mismatch right after a CDN purge, the failure is rarely random Unity behavior. It is almost always mixed deployment state: partial uploads, profile drift between build and player, edge caches returning mismatched objects, or the player retaining an old cached catalog while the origin moved forward.

This guide gives you a fast triage route to fix the mismatch, separate client cache issues from origin issues, and prevent the next rollout from shipping partial catalog state.

Problem signature

Typical indicators include one or more of:

Addressables logs hash mismatch while loading or updating the remote catalog
Players fetch a new catalog.json (or platform-named catalog) but still resolve old bundle hashes or 404 bundle URLs
CDN purge completed, but some edge nodes still serve a stale hash file or stale catalog while others serve the new set
QA sees inconsistent behavior across regions, carriers, or devices that share no obvious code difference
First launch after an update fails, while reinstall or cache clear “fixes” it for some users only

Symptom phrases worth matching in logs and monitors include remote catalog, hash mismatch, catalog update, Unable to load dependent bundle, and CRC or hash failures immediately after catalog initialization.

Root cause in plain terms

A remote catalog release is valid only when these pieces agree:

The catalog JSON your client downloads
The companion catalog hash file Addressables uses to validate that JSON
Every remote bundle URL the catalog references, at the paths your active Addressables profile resolves at runtime

If you purge edge caches but upload in multiple steps, upload to the wrong folder for one platform profile, or switch traffic before every file in the release set is reachable, clients observe a mixed generation. Hash validation fails because the hash file does not correspond to the catalog bytes your player received, or the catalog references bundle internal IDs that are not present at the remote load path.

Player-side caching adds a second layer: even when the origin is correct, a device can still run with an old cached catalog unless you clear Addressables cache or bump paths in a controlled way.

Tell apart CDN or origin drift from local player cache

Before you change hosting configuration, run this split:

Origin looks wrong from curl from two networks and two regions: treat as deployment or CDN misconfiguration.
Origin looks correct from curl, but the game still mismatches until cache clear: treat as player cache or stale catalog path in your initialization flow.
Only some platforms fail: compare per-platform build folder names and profile variables (RemoteLoadPath substitutions) for that platform’s catalog file names.

Step-by-step fix

1) Verify the exact bytes clients receive at the live URL

Fetch both the catalog and hash files directly from the same host names your shipping build uses, not only from the editor.

Typical file naming patterns include:

catalog_<platform>.json
catalog_<platform>.hash

Your Addressables version and platform settings may generate different names; always copy the names from your ServerData output folder for the profile you built.

Confirm the hash value matches the current JSON content. Practical checks:

Download both files with a browser or curl using the production base URL.
Compare file sizes and last-modified metadata between regions if you use a multi-region CDN.
If your CDN supports conditional requests, note whether ETag or Last-Modified jumps between requests to the same URL. Wild swings often mean you still have multiple valid generations behind one path.

2) Confirm Addressables profile paths are aligned for every release lane

In Addressables Profiles, verify for the profile used by this build:

RemoteBuildPath points to your build output location used to produce this drop
RemoteLoadPath resolves to the exact CDN or origin path players use at runtime
Platform folder naming and case match object keys if your bucket is case-sensitive
You did not change profile variables between content build and player build without rebuilding Addressables content

A profile mismatch can produce correct-looking artifacts on disk while publishing them under the wrong keys. That looks exactly like flaky CDN behavior.

3) Rebuild and upload as one atomic release

Do not upload catalog first and bundles later.

Use one release step that publishes:

catalog JSON
catalog hash
all changed or new bundles referenced by that catalog

If your deploy tool cannot publish atomically, upload into a new versioned directory (for example .../releases/2026-05-01-a/) and switch routing or player base paths only after all objects in that directory pass verification.

4) Purge only after upload completes and verification passes

Run CDN purge after the full file set is live at the target paths, not before.

When purging:

Prefer path-scoped invalidations for the catalog and hash keys first, then bundles if needed
Avoid overly broad wildcards that flush unrelated assets still depended upon by older clients unless you intend a breaking migration
Wait for purge propagation before you trust smoke tests from distant regions

5) Validate HTTP caching headers for catalog and hash objects

Catalog and hash files should not behave like long-lived immutable bundles unless you intentionally version paths per release.

Confirm:

Short TTL or explicit revalidation behavior for JSON and hash paths when you overwrite in place
Correct Content-Type so intermediaries do not transform bodies
No accidental compression or middleware that alters bytes between origin and client for small JSON responses unless every client supports it consistently

If only edge locations fail, compare response headers between a failing POP and a working POP.

6) Clear player-side Addressables cache in your verification pass

On at least one clean test device or VM:

Clear the application’s data or use Addressables APIs such as Addressables.ClearDependencyCacheAsync for your labels or keys as appropriate for your version (consult current Addressables API for your package version).
Launch the build and force catalog initialization.
Confirm no hash mismatch and remote assets resolve.

If the failure disappears only after cache clear while curl shows a healthy origin, add a catalog version bump or remote load path strategy for forced migration and document it for live ops.

7) Add a minimal CI or release gate that fails fast

Before you promote a build to production:

Compare the hash file on disk after content build to an HTTP GET of the deployed hash URL
Optionally verify at least one representative bundle URL from the catalog resolves with HTTP 200
Fail the pipeline if catalog JSON references bundle internal IDs that are missing from the upload manifest

This catches “half copied ServerData” mistakes before players touch the CDN.

Verification checklist

catalog.json (or your platform catalog name) and catalog.hash match on live URL across two networks
Bundle files referenced by catalog are reachable at the resolved remote URLs
No cross-region mismatch in CDN edge responses for the same object path
First launch after cache clear succeeds
Repeat launch succeeds without catalog fallback errors
Logs show a single catalog generation identifier or consistent remote paths across sessions
Staging and production do not share overwrite-prone paths unless you intend in-place updates with tight TTL policy

Alternative fixes for edge cases

Mismatch only in one region: Invalidate region-specific edge caches and compare cache keys; some providers require explicit “region flush” operations.
Mismatch only on one platform: Verify platform-specific output folders and that your player build points at the platform profile you published.
Mismatch only after hotfixes: Prefer versioned release directories instead of in-place overwrite until you retire older clients.
Editor works, players fail: Compare RemoteLoadPath substitution at runtime with logging; editor often uses local paths that hide profile mistakes.
Invalid key errors after catalog loads: You may have crossed catalog generations against keys; see the invalid-key guide linked below.

Prevention tips

Treat catalog, hash, and bundles as one deployment unit with a checklist.
Add a pre-publish script that validates catalog references before upload.
Keep catalog and hash TTL behavior conservative when you reuse URLs across releases.
Log active catalog version or remote folder at startup to simplify incident triage.
Document rollback by keeping previous versioned directories intact until telemetry stabilizes.

FAQ

Why does this happen even after CDN purge?

Purge timing can still expose mixed state if files were uploaded in phases, if purge ran before upload finished, or if different edges still hold distinct generations of the same logical URL.

Should we overwrite files in place or use versioned folders?

Versioned folders are safer for rollback and reduce partial-state risk during rollout. In-place overwrite demands disciplined TTL and immediate purge after upload.

Is this a Unity version bug?

Usually no. Most incidents come from deployment order, profile mismatches, stale edge behavior, or player cache retaining an older catalog generation.

Why does hash mismatch sometimes correlate with installs from different store tracks?

Different tracks can point at different remote URLs or build IDs. Confirm each track’s Addressables profile variables and the ServerData drop wired into that track.

Does clearing CDN cache fix player devices automatically?

No. Players may still hold Addressables’ local catalog cache until cleared or until your app forces a new catalog location.