Hydration Guardian

Overview

Ensures zero-mismatch integrity between server-rendered HTML and client-side React trees. Covers hydration error diagnosis, selective hydration via Suspense boundaries, deterministic data bridges with the React 19 use() hook, 'use cache' for eliminating data drift, two-pass rendering for client-only content, React 19's single-diff hydration error reporting for pinpointing exact mismatches, and automated validation of rendered DOM state.

When to use: Debugging hydration mismatch errors, fixing text content mismatches, handling browser extension DOM pollution, implementing deterministic data bridges, optimizing SSR/client hydration performance, setting up error monitoring with onRecoverableError.

When NOT to use: Client-only React applications without SSR, static sites without hydration, API-only backends.

Quick Reference

Pattern	Approach	Key Points
Selective hydration	`<Suspense fallback={...}>` boundary	Hydrates independently; prioritizes user interaction
Deterministic bridge	`use(serverPromise)` instead of useEffect	Direct server-to-client data transition (React 19)
Cache directive	`'use cache'` in data fetchers	Share exact server result with client during hydration
Two-pass rendering	`useState` + `useEffect` for client-only	First render matches server; second adds client content
Client-only skip	`next/dynamic` with `ssr: false`	Exclude component from server render entirely
Error monitoring	`onRecoverableError` on `hydrateRoot`	Detect and report silent hydration recovery
Error reporting	React 19 single-diff error format	Pinpoints exact mismatch location with unified diff output
Error callbacks	`onUncaughtError`, `onCaughtError`	Granular error handling on `createRoot`/`hydrateRoot`
Date/time safety	UTC normalization or server-synced context	Prevent locale-dependent hydration mismatches
Extension resilience	Test with common browser extensions active	Detect DOM pollution from translators, dark-mode tools

Hydration Error Diagnosis

Error Message	Likely Cause	Corrective Action
`Text content did not match`	Non-deterministic render (dates, random values)	Use two-pass rendering or `suppressHydrationWarning`
`Expected server HTML to contain`	Client renders content server did not	Move client-only code to `useEffect` or dynamic import
`Hydration failed`	Invalid HTML nesting (`<p>` inside `<p>`)	Fix HTML structure; browsers auto-correct causing drift
`Extra attributes from server`	Server-only attributes not on client	Ensure attribute parity or use `suppressHydrationWarning`
`There was an error while hydrating`	Extension-modified DOM or major mismatch	Check for browser extensions; verify HTML validity

Common Mistakes

Mistake	Correct Pattern
Using `suppressHydrationWarning` on container elements	Fix the root cause; suppress only on leaf elements with unavoidable differences
Accessing `window` or `document` in the render body	Wrap client-only code in `useEffect` or use `next/dynamic` with `ssr: false`
Using `Math.random()` or `new Date()` without stable seeds	Use UTC normalization, server-cached values, or two-pass rendering
Ignoring silent hydration recovery in production	Configure `onRecoverableError` on `hydrateRoot` to log and monitor
Using `dangerouslySetInnerHTML` with server/client mismatch	Ensure identical content or use a dedicated `key` change to force remount
Checking `typeof window !== 'undefined'` in render	Use two-pass rendering; the check runs on server too (it returns false)
Nesting `<p>` inside `<p>` or `<div>` inside `<p>`	Fix invalid HTML nesting; browsers correct it causing server/client drift

Delegation

Scan rendered pages for hidden hydration warnings: Use Explore agent with Chrome DevTools to run the hydration audit script
Fix hydration mismatches across multiple routes: Use Task agent to isolate, correct, and verify each affected component
Design hydration-safe architecture for new features: Use Plan agent to select between Suspense boundaries, two-pass rendering, and cache patterns

References

Common Mismatches -- causes, diagnosis, and fixes for hydration mismatch errors including dates, locales, HTML nesting, and browser extensions
Selective Hydration -- Suspense-based selective hydration, streaming SSR, two-pass rendering, and client-only components
Use Cache Patterns -- data drift prevention, Next.js use cache directive, React 19 use() hook, deterministic data bridges
Validation Techniques -- automated DOM verification, mutation monitoring, onRecoverableError, and production hydration monitoring