Hydration failed
Hydration failed because the server rendered HTML didn't match the clientThe page React built in the browser came out different from the HTML the server sent.
What it means
A Next.js page is rendered twice: once on the server, which sends the HTML, and once in the browser, where React takes that HTML over. Taking it over is called hydration. If the browser's first render produces different HTML, React reports this error. The exact wording varies between React versions; the cause is the same.
Common causes
- HTML that is not allowed to nest. A
<div>inside a<p>, or a<p>inside another<p>. - Browser-only values read during render. Checking
typeof window, or readingwindoworlocalStoragewhile rendering, so the browser renders something the server could not. - Values that differ between the two renders. The current date or time rendered straight into the page is the common one.
- Something changed the HTML on the way. A browser extension, a CSS-in-JS library that is set up wrong, or a CDN setting that rewrites the HTML.
Ways to fix it
- Correct the HTML nesting.
- Move browser-only values into
useEffect, so they appear after hydration instead of during it. - For a component that cannot render on the server at all, Next.js offers
dynamic(() => import(...), { ssr: false }). - For one element whose text genuinely cannot match, such as a timestamp,
suppressHydrationWarningsilences it. It only works one level deep, and it is an escape hatch, not a fix.
A prompt to fix it
Paste it into your AI coding tool and fill in the parts in angle brackets. It asks the tool to find the cause and show you before it changes anything.
Paste it, then fill in the <angle brackets>
My Next.js app shows: Hydration failed because the server rendered HTML didn't match the client.
<paste the full error, including the component names and the difference it shows>
Find the component where the server and the browser render different output. Check, in this order:
1. HTML that cannot nest, such as a <div> or another <p> inside a <p>.
2. Anything read during render that only exists in the browser: window, localStorage, typeof window checks.
3. Values that change between the two renders: dates, times, random numbers.
Tell me which one it is, with the file and line.
Fix it the narrowest way: correct the HTML, or move browser-only values into useEffect so they appear after hydration. Use suppressHydrationWarning only on a single element whose text cannot match, such as a timestamp, and tell me if you do. Do not turn off server rendering for the whole page.How to check it is fixed
- Reload the page with the browser console open: the hydration error is gone.
- Open the page in a private window with extensions off. If the error only appears with extensions on, an extension is changing the page, not your code.
Tested prompts that help
- Hand It An Error — If the fix above does not do it, or your error is close to this one but not quite, this prompt hands your AI tool the whole error, what you expected, the last thing you changed and what you already ruled out, and makes it name the cause before it changes anything. Test log: Pass, ChatGPT (Pro), September 27, 2026; Pass, Claude.ai (Fable 5.1 Max), September 27, 2026.
Sources
Everything above comes from these pages. We read them on September 27, 2026; if one has changed since, it wins.