fix(persist): prevent race condition during concurrent rehydrate calls #3336

Niyaz-Mazhitov · 2025-12-27T07:10:17Z

Summary

Fixes race condition in persist middleware when multiple rehydrate() calls happen concurrently.

Problem

When using async storage, if rehydrate() is called multiple times before the first hydration completes, all hydrations run in parallel and results are applied in unpredictable order. This causes:

Stale state being applied over newer state
onFinishHydration callbacks firing multiple times
Inconsistent state after hydration

Solution

Added a hydrationVersion counter that:

Increments at the start of each hydrate() call
Is checked after each async step (getItem, migrate, before applying state)
Aborts the hydration if a newer one has started

This ensures only the most recent rehydrate() call applies its state.

Test plan

Added test: multiple concurrent rehydrate() calls (only last one wins)
Added test: async migration abort when newer hydration starts
Added test: state changes during hydration behavior
All existing persist tests pass (42 tests)

Added hydrationVersion counter to track and invalidate stale hydrations. When multiple rehydrate() calls happen concurrently, only the last one applies its state, preventing race conditions with async storage. - Added hydrationVersion counter incremented on each hydrate() call - Added version checks after each async step (getItem, migrate, set) - Added 3 tests for concurrent rehydration scenarios

vercel · 2025-12-27T07:10:21Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
zustand-demo	Ready	Preview, Comment	Jan 12, 2026 5:48am

codesandbox-ci · 2025-12-27T07:10:38Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Niyaz-Mazhitov · 2025-12-27T07:41:09Z

If needed, I can provide a minimal reproduction sandbox.
Let me know if you'd like additional tests or adjustments, happy to iterate.

dai-shi

Thanks for the suggestion, and working on it. I may need to take a second look.
I wonder if anyone else would like to give a review.

src/middleware/persist.ts

pkg-pr-new · 2025-12-29T10:18:58Z

demo
starter
```
npm i https://pkg.pr.new/zustand@3336
```

commit: 627706d

Niyaz-Mazhitov · 2025-12-29T11:05:49Z

Thanks a lot for the review and for looping in another reviewer!
I’ve updated the implementation to use the simpler version-check approach we discussed.
If you’d like me to adjust anything further or add more tests / comments, I’m happy to do so.

dai-shi

simplify further?

src/middleware/persist.ts

…on' into fix/persist-hydration-race-condition

dai-shi

LGTM
Now, it's readable. Thanks for your contribution.

I'll merge this PR when I prepare a new release. Maybe next year. Anyone can feel free to give a review until then.

Niyaz-Mazhitov · 2025-12-29T13:33:40Z

Thank you for the thorough review and patience! 🙏 Learned a lot from this process. Happy to contribute more in the future! 🚀

dbritto-dev · 2025-12-29T14:16:02Z

@Niyaz-Mazhitov @dai-shi LGTM

Bumps [zustand](https://github.com/pmndrs/zustand) from 5.0.9 to 5.0.10. Release notes *Sourced from [zustand's releases](https://github.com/pmndrs/zustand/releases).* > v5.0.10 > ------- > > This version includes a fix to the `persist` middleware for an edge case. > > What's Changed > -------------- > > * fix(persist): prevent race condition during concurrent rehydrate calls by [`@Niyaz-Mazhitov`](https://github.com/Niyaz-Mazhitov) in [pmndrs/zustand#3336](https://redirect.github.com/pmndrs/zustand/pull/3336) > > New Contributors > ---------------- > > * [`@max-programming`](https://github.com/max-programming) made their first contribution in [pmndrs/zustand#3310](https://redirect.github.com/pmndrs/zustand/pull/3310) > * [`@oleksandr-danylchenko`](https://github.com/oleksandr-danylchenko) made their first contribution in [pmndrs/zustand#3319](https://redirect.github.com/pmndrs/zustand/pull/3319) > * [`@MateuszSobiech`](https://github.com/MateuszSobiech) made their first contribution in [pmndrs/zustand#3334](https://redirect.github.com/pmndrs/zustand/pull/3334) > * [`@EduardoRangelG`](https://github.com/EduardoRangelG) made their first contribution in [pmndrs/zustand#3326](https://redirect.github.com/pmndrs/zustand/pull/3326) > * [`@1mehdifaraji`](https://github.com/1mehdifaraji) made their first contribution in [pmndrs/zustand#3339](https://redirect.github.com/pmndrs/zustand/pull/3339) > * [`@kamja44`](https://github.com/kamja44) made their first contribution in [pmndrs/zustand#3349](https://redirect.github.com/pmndrs/zustand/pull/3349) > * [`@Niyaz-Mazhitov`](https://github.com/Niyaz-Mazhitov) made their first contribution in [pmndrs/zustand#3336](https://redirect.github.com/pmndrs/zustand/pull/3336) > > **Full Changelog**: <pmndrs/zustand@v5.0.9...v5.0.10> Commits * [`003b0a7`](pmndrs/zustand@003b0a7) 5.0.10 * [`9bb7f3b`](pmndrs/zustand@9bb7f3b) chore(deps): update dev dependencies ([#3353](https://redirect.github.com/pmndrs/zustand/issues/3353)) * [`d0cb549`](pmndrs/zustand@d0cb549) fix(persist): prevent race condition during concurrent rehydrate calls ([#3336](https://redirect.github.com/pmndrs/zustand/issues/3336)) * [`59e8783`](pmndrs/zustand@59e8783) test: remove eslint-disable for no-unused-expressions ([#3349](https://redirect.github.com/pmndrs/zustand/issues/3349)) * [`db6fe66`](pmndrs/zustand@db6fe66) docs(CONTRIBUTING): fix 'npm install' to 'pnpm install' ([#3350](https://redirect.github.com/pmndrs/zustand/issues/3350)) * [`8f1d45a`](pmndrs/zustand@8f1d45a) Fix formatting and punctuation in third-party libraries doc ([#3346](https://redirect.github.com/pmndrs/zustand/issues/3346)) * [`74d0aec`](pmndrs/zustand@74d0aec) Add zustand-mutable middleware link ([#3343](https://redirect.github.com/pmndrs/zustand/issues/3343)) * [`f912630`](pmndrs/zustand@f912630) Add zustand-mmkv-storage to third-party libraries ([#3339](https://redirect.github.com/pmndrs/zustand/issues/3339)) * [`4f1f963`](pmndrs/zustand@4f1f963) docs: add memoized selector usage with `useStore` ([#3320](https://redirect.github.com/pmndrs/zustand/issues/3320)) * [`aa2da00`](pmndrs/zustand@aa2da00) docs: fix navigation order for comparison and tutorial markdowns ([#3326](https://redirect.github.com/pmndrs/zustand/issues/3326)) * Additional commits viewable in [compare view](pmndrs/zustand@v5.0.9...v5.0.10) [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility\_score?dependency-name=zustand&package-manager=npm\_and\_yarn&previous-version=5.0.9&new-version=5.0.10)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- Dependabot commands and options You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

vercel bot deployed to Preview December 27, 2025 07:10 View deployment

dai-shi reviewed Dec 29, 2025

View reviewed changes

src/middleware/persist.ts Outdated Show resolved Hide resolved

dai-shi requested a review from dbritto-dev December 29, 2025 10:18

fix(persist): refactor simplify hydration abort logic

201f79e

vercel bot deployed to Preview December 29, 2025 10:41 View deployment

Niyaz-Mazhitov requested a review from dai-shi December 29, 2025 11:02

dai-shi reviewed Dec 29, 2025

View reviewed changes

src/middleware/persist.ts Show resolved Hide resolved

src/middleware/persist.ts Show resolved Hide resolved

fix(persist): refactor use consistent comment pattern for abort checks

e015373

vercel bot deployed to Preview December 29, 2025 12:22 View deployment

Niyaz-Mazhitov requested a review from dai-shi December 29, 2025 12:22

fix(persist): refactor remove redundant abort checks

d4f3414

vercel bot deployed to Preview December 29, 2025 12:53 View deployment

dai-shi reviewed Dec 29, 2025

View reviewed changes

src/middleware/persist.ts Outdated Show resolved Hide resolved

fix(persist): refactor remove unnecessary migrationResult check

f7a6215

Niyaz-Mazhitov requested a review from dai-shi December 29, 2025 13:15

Merge branch 'main' into fix/persist-hydration-race-condition

fd6a2bf

vercel bot deployed to Preview December 29, 2025 13:20 View deployment

Merge remote-tracking branch 'fork/fix/persist-hydration-race-conditi…

f83a4ff

…on' into fix/persist-hydration-race-condition

vercel bot deployed to Preview December 29, 2025 13:27 View deployment

dai-shi approved these changes Dec 29, 2025

View reviewed changes

dbritto-dev approved these changes Dec 29, 2025

View reviewed changes

dai-shi added this to the v5.0.10 milestone Dec 30, 2025

Merge branch 'main' into fix/persist-hydration-race-condition

627706d

vercel bot deployed to Preview January 12, 2026 05:48 View deployment

dai-shi merged commit d0cb549 into pmndrs:main Jan 12, 2026
32 checks passed

Uh oh!

fix(persist): prevent race condition during concurrent rehydrate calls #3336

fix(persist): prevent race condition during concurrent rehydrate calls #3336

Conversation

Niyaz-Mazhitov commented Dec 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Test plan

Uh oh!

vercel bot commented Dec 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codesandbox-ci bot commented Dec 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Niyaz-Mazhitov commented Dec 27, 2025

Uh oh!

dai-shi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pkg-pr-new bot commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Niyaz-Mazhitov commented Dec 29, 2025

Uh oh!

dai-shi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dai-shi left a comment

Choose a reason for hiding this comment

Uh oh!

Niyaz-Mazhitov commented Dec 29, 2025

Uh oh!

dbritto-dev commented Dec 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Niyaz-Mazhitov commented Dec 27, 2025 •

edited

Loading

vercel bot commented Dec 27, 2025 •

edited

Loading

codesandbox-ci bot commented Dec 27, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 29, 2025 •

edited

Loading