Apollo Client cache persistence: schema version mismatch during hydration

Managing Cache Versioning

Apollo Client and apollo3-cache-persist do not provide a native versioning system for persisted state. The InMemoryCache assumes that the data restored from local storage conforms to the current schema and normalization rules. When the schema changes—such as renaming fields or altering type structures—the hydration process may inject stale or incompatible data into the cache, leading to runtime errors or UI inconsistencies.

Recommended Versioning Strategy

The most reliable strategy is to implement a manual version check during the application's initialization phase, before the persistCache call is executed. By storing a version identifier alongside the cache data, you can determine if the persisted state is compatible with the current build.

Implementation Steps:

1. Define a constant CACHE_VERSION in your application configuration.
2. Before calling persistCache, retrieve the stored version from local storage.
3. Compare the stored version with the current CACHE_VERSION.
4. If the versions mismatch, clear the persistence storage (e.g., localStorage.clear() or removing the specific cache key) before proceeding with hydration.

const CACHE_VERSION = '1.2.0';
const STORED_VERSION = localStorage.getItem('apollo-cache-version');

if (STORED_VERSION !== CACHE_VERSION) {
  localStorage.removeItem('apollo-cache-persist');
  localStorage.setItem('apollo-cache-version', CACHE_VERSION);
}

// Proceed to persistCache()...

Partial Invalidation

Apollo Client does not provide a native mechanism to partially invalidate specific types or fields during the restore process of apollo3-cache-persist. The persistence layer treats the cache as a serialized blob of the normalized store. If you require partial invalidation, you must manually transform the persisted JSON object before it is passed back into the InMemoryCache, or utilize cache.evict() and cache.gc() immediately after hydration to prune known stale entities.

Verification and Assumptions

This approach assumes the use of apollo3-cache-persist and a standard InMemoryCache setup. To verify a mismatch is occurring, inspect the local storage entry for your cache and compare the JSON keys against your current GraphQL fragment definitions.

Diagnostic Detail Needed: Are you using a custom dataIdFromObject function? If your normalization logic has changed, the cache is structurally invalid regardless of the schema version, and a full clear is mandatory.