Skip to content
Tutorials Center
My learning

Topics

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.

JSX
// Typical cause: different output on server and client
function Greeting() {
  return <p>Rendered at {Date.now()}</p>; // differs on every render
}

Try it

Fix: render the same thing first, change after mount
Invalid nesting: the browser rewrites server HTML
suppressHydrationWarning keeps the server text

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.
  • suppressHydrationWarning works 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.
  • useId values 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 Suspense boundary limits the damage: only the boundary that failed re-renders on the client, not the whole page.