Redux Toolkit preloadedState limits during state shape evolution

Direct answer

Redux Toolkit does not version, migrate, or validate preloadedState. It passes the object straight to your root reducer. To prevent incompatible snapshots from breaking your store, wrap persisted data in a versioned envelope, run migrations before store creation, and validate the result with a schema check. If either step fails, discard the snapshot and fall back to undefined so reducers initialize with their defaults.

Confirmed facts vs. likely explanation

Confirmed: configureStore({ preloadedState }) forwards that value to the root reducer. If your reducer expects user.profile.name but the persisted shape has user.name, the reducer receives undefined and may throw or silently store wrong data.

Likely explanation for hard-to-debug crashes: old snapshots contain obsolete keys or changed types (for example, a string where an array is now expected). Because Redux does not automatically merge or prune the incoming state, stale fields persist in the tree and can cause runtime errors when components assume the new shape.

Implementation pattern

1. Version every write. Persist { version: 3, state: serializedRootState } instead of the bare state. Increment version whenever a reducer's shape changes.
2. Migrate on read. Keep an ordered list of migration functions keyed by version. On load, apply each migration sequentially until the snapshot reaches the current version.
3. Validate before hydration. Use Zod (or a similar schema library) to parse the migrated object. On failure, return undefined rather than passing bad data to configureStore.
4. Pass only clean state. Call configureStore({ reducer, preloadedState: validated }).

Example skeleton:

const CURRENT_VERSION = 3;

const migrations = {
  1: (s) => ({ ...s, user: { profile: { name: s.user.name } } }),
  2: (s) => ({ ...s, settings: { theme: s.settings.theme ?? 'light' } }),
};

function loadState() {
  const raw = localStorage.getItem('appState');
  if (!raw) return undefined;
  try {
    const parsed = JSON.parse(raw);
    let state = parsed.state;
    for (let v = parsed.version; v < CURRENT_VERSION; v++) {
      const migrate = migrations[v];
      if (!migrate) return undefined;
      state = migrate(state);
    }
    return RootStateSchema.parse(state);
  } catch {
    return undefined;
  }
}

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

Verification

To confirm this works in your app: persist a v1 snapshot, bump CURRENT_VERSION, reload, and inspect store.getState(). The migrated keys should match the current reducer's initial shape, and no obsolete keys should remain.

One diagnostic question

Is your hydration synchronous (e.g., localStorage) or asynchronous (e.g., IndexedDB, network fetch)? If asynchronous, preloadedState cannot be used directly; you would initialize the store with defaults and dispatch a rehydration action after the promise resolves.