Debugging field guide
Find the first wrong state transition.
A UI symptom often appears several updates after the state first went wrong. The useful question is not “what is the state now?” but “which action changed this path, from what, and where was it called?”
Short version: name the store, name the action, reproduce once, then inspect the earliest unexpected path change. Preserve a redacted trace before trying fixes.
A six-step workflow
Make the store identifiable
Give each store a stable name. This matters in apps with several stores because a single global stream is otherwise easy to misread.
Name important updates
Zustand's official devtools middleware accepts action
names as the third set argument. A label such as
cart/addItem is more useful than an anonymous update.
Write expected and actual behavior first
One sentence each prevents the investigation from drifting. Include the smallest reliable reproduction and avoid customer data.
Record one clean reproduction
Start from a known state. Perform only the actions needed to trigger the bug. Noise makes the first wrong transition harder to see.
Follow the changed path backward
Start at the visible symptom, identify its backing state path, and move backward until you find the first unexpected before/after value. Check the associated action and best-effort call-site.
Preserve evidence, then test a fix
Export a redacted session or record the relevant transitions. Change one cause at a time and replay the same reproduction.
What to check when the timeline looks wrong
-
The store may not be registered, or the action may be bypassing the
wrapped
set. - Anonymous action labels can hide which code path initiated an update.
- A computed UI value may be wrong even when stored state is correct.
- Persisted or hydrated state can create an earlier transition than the click you are watching.
- Call-sites are best-effort debugging hints, not proof of causality.
Privacy before sharing
State can contain tokens, email addresses and customer content. Remove or redact sensitive keys before sharing a trace. Zustand DevTools keeps inspection local and supports redacted export, but the person exporting remains responsible for reviewing the file.
Inspect the next reproduction in Chrome.
Stores, Timeline and safe time travel are free. Three Trace Session previews are included; unlimited sessions are €9.99 plus applicable tax, once.
Install Zustand DevToolsStill blocked after reviewing one redacted trace? Submit it to the Zustand Bug Clinic. The first five suitable bugs received by 18 September 2026 get a short written diagnosis at no charge in exchange for three follow-up answers.