Time and randomness
Dates, counters, UUIDs, random ordering, and expiring state differ across executions.
Quick reference · Print-friendly
Hydration diagnosis field guide
Trace identity first, then scheduling, then payload cost.
Trace the lifecycle
| Stage | What exists | What can fail | Evidence |
|---|---|---|---|
| Server render | HTML snapshot + serialized inputs | Nondeterminism, leaked personalization, slow data | Response HTML, server spans, TTFB |
| Browser paint | DOM and native browser behavior | Layout shift, misleading controls, blocked resources | Filmstrip, LCP, resource waterfall |
| Code startup | Downloaded and evaluated modules | Large bundles, long tasks, dependency waterfalls | Coverage, CPU profile, TBT/INP |
| Hydration | Client tree matched to existing DOM | Mismatch, stale snapshot, boundary suspension | Recoverable errors, component stack, traces |
| Interactive | Managed state, events, effects, subscriptions | Queued intent, lost clicks, slow updates | Interaction traces, field INP, task success |
Mismatch checklist
Environment branches
Rendering on window, storage, viewport, media queries, or feature detection changes the tree.
Data races
The client reads fresher data instead of hydrating from the serialized server snapshot.
Markup correction
Invalid nesting causes the browser parser to repair HTML before the runtime matches it.
Locale and timezone
Formatting depends on defaults that are not identical across server and browser.
DOM mutation
Extensions, scripts, personalization, or A/B tools modify nodes before hydration.
Repair in this order
- Capture the exact mismatch and component stack through development warnings or
onRecoverableError. - Compare the server HTML with the client’s first render—not with the eventual post-effect UI.
- Serialize every input that shapes initial markup and initialize the client from that snapshot.
- Move unavoidable browser-only differences after hydration or use the same stable placeholder.
- Place Suspense boundaries around independently loadable, useful regions—not around arbitrary component sizes.
- Reduce shipped code and work. Selective hydration prioritizes cost; it does not delete cost.
- Use suppression only for an unavoidable leaf whose mismatch cannot affect structure or behavior.
Interview phrases worth earning
“Visible is not equivalent to interactive; I would inspect the gap between paint, code availability, and boundary hydration.”
“The client should hydrate from the server snapshot, then converge on fresher state.”
“Streaming and selective hydration share Suspense boundaries, but one schedules HTML delivery and the other schedules client activation.”
“Boundary placement should follow independent user intent, latency, and failure—not the component-file tree.”