How to Fix Hydration Errors in Next.js

The server rendered one tree. The browser expected another. Find the first mismatch instead of silencing the warning.

By Shadorux · September 3, 2026 · 7 min read · Next.js · Debugging

Hydration is the handoff between server HTML and the React tree booted in the browser. A hydration error means those trees do not describe the same markup at the same time.

Signal check
Read the first mismatch in the console. Later errors are often the same divergence cascading through the tree.

Common causes

Rendering window, localStorage, dates, or random values during the first render.
Branching on a client-only condition before the component has mounted.
Invalid HTML nesting that the browser repairs before React sees it.

Keep the first render deterministic

Move browser-only reads behind a small client boundary and use the same fallback on both sides.

useEffect(() => {
  setTheme(window.localStorage.getItem("theme"));
}, []);

Use suppressHydrationWarning only for a deliberately different leaf, such as a client-owned timestamp—not to hide a mismatched layout.

Still stuck with a React or Next.js bug? See React & Next.js debugging help.

Common causes

Keep the first render deterministic

Related notes