React Reference ยท react-dom Client APIs
Hydration mismatch errors in React
Why server and client HTML differ in React, how to read hydration mismatch errors, and fix them: invalid nesting, time and random values, browser-only data.
A hydration mismatch means the HTML sent by the server is not what React produces when it renders the same components in the browser. During hydrateRoot, React compares the two. When they differ it reports an error such as "Hydration failed because the server rendered text didn't match the client", discards the server markup for the affected part, and renders again on the client.
The page still works, but you lose the benefit of server rendering for that part, users may see a flash of changed content, and the error is a sign of real bugs. The fix is almost always to make the first client render identical to the server render, and move anything environment-specific into an effect.
// Typical cause: different output on server and client function Greeting() { return <p>Rendered at {Date.now()}</p>; // differs on every render }
Try it
Common causes
| Cause | What happens | Fix |
|---|---|---|
Date.now(), new Date(), Math.random() in render |
Different value on server and client | Compute in an effect, or pass one value from the server as a prop |
typeof window !== 'undefined' in render |
Different branch on each side | Use a mounted flag set in useEffect, as above |
Reading localStorage or matchMedia in render |
Not available on the server | Read inside an effect, or useSyncExternalStore with a getServerSnapshot |
Invalid HTML nesting (<div> in <p>, <a> in <a>, <tr> outside <tbody>) |
The browser parser reshapes the DOM | Correct the structure |
| Locale or time zone formatting | Server and user differ | Format on the client after mount, or fix the locale and zone |
| Browser extensions or CDNs that edit HTML | Extra nodes appear | Test without them; they are not your bug |
| Different data between server render and client | Props differ | Serialize the server data and reuse it on the client |
Usage notes
- Read the console message in development. React 19 prints the mismatch with a diff of expected and actual DOM, which is far clearer than older versions.
- Use
onRecoverableError(options) to send hydration failures to monitoring. In production they are the only sign. suppressHydrationWarningworks one level deep on an element and only silences the warning for its own attributes and text. It does not fix or patch the DOM, as the third example shows, and should be rare: a timestamp is the standard use.useIdvalues are stable across server and client for the same tree, so use them rather than counters or random IDs.- An element missing on one side shifts every sibling after it. Conditionally rendered content that differs between environments is the usual suspect.
- A
Suspenseboundary limits the damage: only the boundary that failed re-renders on the client, not the whole page.