Redux state hydration and schema mismatch during preloadedState injection

Recommended pattern

Do not pass raw parsed JSON directly to preloadedState. Treat persisted storage as untrusted input: parse it defensively, check a reserved schema version, run ordered migrations, validate the result, and only then pass the normalized object to configureStore or createStore.

Confirmed behavior vs likely cause

Redux core has no native versioning or migration API. createStore and configureStore accept preloadedState, and reducers receive undefined for missing slices. A reducer that defaults its parameter to an initial state object survives missing keys safely. The common failure is an old persisted tree missing a newly added slice, so code like state.newFeature.field throws because state.newFeature is undefined. Extra top-level keys are usually ignored by combineReducers, but a custom root reducer may preserve them.

Steps for this case

1. Persist state with a reserved field such as __schemaVersion.
2. On load, read the raw string and JSON.parse inside try/catch. On malformed JSON or unexpected types, fall back to the initial state instead of creating the store with bad data.
3. Read the persisted version. Treat an absent version as legacy 0.
4. Run migrations in ascending order. Each migration must be immutable, return a new object, and default missing slices to the reducer's initial state.
5. Re-validate the migrated shape against the current state definition. Discard invalid data and fall back to initial state rather than injecting it.
6. Pass the final object as preloadedState.

function loadPersistedState() {
  try {
    const raw = localStorage.getItem("reduxState");
    if (!raw) return undefined;
    const parsed = JSON.parse(raw);
    if (typeof parsed !== "object" || parsed === null) return undefined;
    return migrate(parsed);
  } catch {
    return undefined;
  }
}

function migrate(state) {
  const version = state.__schemaVersion ?? 0;
  let next = { ...state };
  if (version < 1) next = migrateV0ToV1(next);
  if (version < 2) next = migrateV1ToV2(next);
  return { ...next, __schemaVersion: CURRENT_VERSION };
}

const store = configureStore({
  reducer: rootReducer,
  preloadedState: loadPersistedState(),
});

Assumptions and verification

This assumes every slice reducer uses default parameters so undefined preloaded state resolves to the initial state. Exact warnings for unknown preloadedState keys differ between Redux versions, Redux Toolkit, and custom root reducers; verify against your installed version. Do not store functions, secrets, or derived server state in client storage.

Verification: create a store with an old persisted object missing a new slice and assert no error is thrown and the new slice equals its reducer initial state. Then persist v0 JSON, upgrade the schema, run the migration, and assert the hydrated state matches the expected migrated shape. Confirm invalid JSON falls back to initial state.

One missing detail that could change the recommendation: are you using vanilla Redux createStore, Redux Toolkit configureStore, or a custom root reducer? Unknown-key handling differs across those configurations.