React Error #418: Hydration failed — server HTML does not match client
Hydration failed because the server rendered HTML didn't match the client
Verified against React 19 source (ReactFiberHydrationContext.js), Next.js docs: react-hydration-error, Stack Overflow #68945655 · Updated April 2026
> quick_fix
The server rendered different HTML than the client would render on the first pass. Find the non-deterministic value (Date.now, Math.random, window.*, user locale) and render it only after mount using useEffect.
// ❌ Mismatches on reload
function Timestamp() {
return <p>{new Date().toLocaleString()}</p>
}
// ✅ Render after hydration
function Timestamp() {
const [ts, setTs] = useState('')
useEffect(() => setTs(new Date().toLocaleString()), [])
return <p suppressHydrationWarning>{ts}</p>
}What causes this error
During SSR, React renders the HTML on the server. On the client, React hydrates by re-rendering the component tree and comparing to the existing DOM. If the first client render produces different markup, React discards the server tree and falls back to client-only rendering — slow, janky, and logged as #418.
How to fix it
- 01
step 1
Check browser console for the mismatch
React logs the expected vs received text. Look for timestamps, randomised IDs, or locale-specific formatting.
- 02
step 2
Move non-deterministic values into useEffect
Anything that depends on window, navigator.language, Date.now, Math.random, or user timezone must render only after mount.
- 03
step 3
For intentional mismatches, add suppressHydrationWarning
React's escape hatch for known-diverging content like timestamps. Only the single element is suppressed, not its children.
- 04
step 4
Check for HTML nesting bugs
<div> inside <p>, <p> inside <p>, or <a> inside <button> — the browser auto-corrects these on the client and diverges from server HTML. Fix the nesting instead of suppressing.
Frequently asked questions
What causes React hydration mismatch?
Anything non-deterministic between server and initial client render: Date.now, Math.random, window.*, navigator.language, or HTML nesting auto-corrected by the browser.
Is suppressHydrationWarning safe to use?
For single elements where divergence is intentional and bounded (like a timestamp), yes. Do not scatter it across the component tree to silence real bugs.
Does Next.js have a special hydration fix?
Next.js 16 adds the `use cache` directive, which lets you render dynamic values on the server without mismatches. See cache-components docs.