Zustand persist middleware loses state or shows defaults in React Native
persisted state is empty after restartShort answer
With AsyncStorage the store hydrates after the first render, so the app briefly shows default values. Wrap AsyncStorage in createJSONStorage, give each store a unique name, and wait for hydration before reading state. A changed version number also discards old saved data unless you migrate.
Fix it fast
1Find out which cause you have
Print the store after startup and again a second later. If the second print has your data, it is hydration timing. If not, it is storage, name or version.
console.log(useBoundStore.persist.hasHydrated(), useBoundStore.getState()); setTimeout(() => console.log(useBoundStore.persist.hasHydrated(), useBoundStore.getState()), 1000);2Match what you see, then jump to its fix
- 1
The first render shows defaults, then the saved values appear.Async storage hydrates after the first renderFix - 2
State is kept in a web build but not on the phone.storage is not set to AsyncStorageFix - 3
One store overwrites another, or some fields reset while others stay.Two stores share one name, or partialize leaves fields outFix - 4
Data disappears right after an app update that changed the store shape.The version changed and old data is ignoredFix
- 1
What does the error look like?
persisted state is empty after restartstore shows default values on first renderlogged out for a moment on app start
Cause 1 of 4
Async storage hydrates after the first render
1Check
With asynchronous storage such as AsyncStorage, the store is not hydrated at the initial render. hasHydrated() reports false at first.
grep -n "persist(" -r src/2Fix
Track hydration in the store and show a loading state until it finishes.
export const useBoundStore = create()(
persist(
(set) => ({ _hasHydrated: false, token: null }),
{
name: 'auth-storage',
storage: createJSONStorage(() => AsyncStorage),
onRehydrateStorage: () => () => {
useBoundStore.setState({ _hasHydrated: true });
},
},
),
);3Verify
On cold start the loading state shows, then the saved values.
# kill the app and open it againConfirmed by zustand.docs.pmnd.rs
Cause 2 of 4
storage is not set to AsyncStorage
1Check
The default storage is localStorage. React Native needs another engine passed through createJSONStorage.
grep -n "createJSONStorage" -r src/2Fix
Set storage to AsyncStorage wrapped with createJSONStorage.
// Expo: npx expo install @react-native-async-storage/async-storage
import AsyncStorage from '@react-native-async-storage/async-storage';
import { persist, createJSONStorage } from 'zustand/middleware';
persist(stateCreator, {
name: 'app-storage',
storage: createJSONStorage(() => AsyncStorage),
});3Verify
Change state, kill and reopen the app. The values remain.
# after reopening, log useBoundStore.getState()Confirmed by zustand.docs.pmnd.rs
Cause 3 of 4
Two stores share one name, or partialize leaves fields out
1Check
name is the storage key and must be unique per store. partialize picks which fields are saved; by default the whole state is.
grep -n "name:\|partialize" -r src/2Fix
Give every persisted store its own name and list the fields you want saved.
persist(stateCreator, {
name: 'cart-storage',
storage: createJSONStorage(() => AsyncStorage),
partialize: (state) => ({ items: state.items }),
});3Verify
Change both stores and reopen the app. Each keeps its own values.
# log both stores after restartConfirmed by zustand.docs.pmnd.rs
Cause 4 of 4
The version changed and old data is ignored
1Check
If the stored version does not match version (default 0), the stored value is not used.
grep -n "version:\|migrate" -r src/2Fix
Raise version when you change the shape and add a migrate function that returns state for the current version.
persist(stateCreator, {
name: 'app-storage',
version: 1,
storage: createJSONStorage(() => AsyncStorage),
migrate: (persisted, version) => {
if (version === 0) {
return { ...persisted, fullName: persisted.name };
}
return persisted;
},
});3Verify
Install the old build, save data, install the new one. The data is still there.
# upgrade the app without clearing storageConfirmed by zustand.docs.pmnd.rs
How do I stop it coming back?
- Wait for hydration before routing on persisted values such as a login token.
- Use a unique name for each store.
- Bump version and write migrate whenever the stored shape changes.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
Android build stops at processDebugManifest in a React Native app
Manifest merger failed
processDebugManifest is the step that merges your AndroidManifest.xml with the manifests of every library.
2 causes, each with a fixMobile apps
Running pod on a React Native project fails with can't find gem cocoapods
can't find gem cocoapods (>= 0.a) with executable pod
The pod command exists, but the Ruby that is running it has no CocoaPods gem.
3 causes, each with a fixMobile apps
React Native Android build cannot find the foojay-resolver-convention plugin
Plugin [id: 'org.gradle.toolchains.foojay-resolver-convention'] was not found in any of the following sources:
The foojay plugin is a settings plugin that Gradle downloads from the Plugin Portal.
3 causes, each with a fixMobile apps
Kotlin and Java compile to different JVM targets in a React Native Android build
'compileJava' task (current target is 1.8) and 'compileKotlin' task (current target is 11)
Gradle refuses to build when the Java task and the Kotlin task target different JVM versions.
3 causes, each with a fixMobile apps
Gradle cannot run node in a React Native Android build
Process 'command 'node'' finished with non-zero exit value 1
The React Native Gradle plugin starts node for bundling.
3 causes, each with a fixMobile apps
The Android emulator opens the app but never connects to Metro or Expo
Metro bundler ECONNREFUSED 127.0.0.1:19001
When the emulator cannot reach Metro, first prove each side on its own: adb sees the emulator, and Metro listens on its port.
4 causes, each with a fix