Interface & Contract
Serialization/rehydration mismatch
Last updated: 4 Mar 2026
Definition
Data serialized on one side cannot be faithfully reconstructed on the other (e.g., server/client), causing UI or logic divergence.
How to fix Serialization/rehydration mismatch?
Stabilize the serialized shape; avoid non-deterministic values; version payloads; add end-to-end serialization tests; align server/client render
Symptoms
Observable signs that may indicate Serialization/rehydration mismatch:
- Hydration warnings or DOM checksum mismatches on initial render.
- Server-rendered markup differs from client render (blinking or reflow).
- Stateful values (dates/random IDs) differ between server and client.
Example Errors:
- Hydration failed because the initial UI does not match what was rendered on the server.
- Unexpected token < in JSON at position 0
- Text content does not match server-rendered HTML