A React hydration error means the browser’s first render does not match the HTML the server already sent. The reliable fix is to find the earliest difference and make both outputs agree—not to silence the warning. React’s hydrateRoot reference says to treat mismatches as bugs and fix them.
What hydration expects
With server rendering, React produces HTML before the page reaches the browser. hydrateRoot(domNode, reactNode, options?) attaches React to that existing HTML so the page can become interactive. The first client render must produce the same content and structure as the server output. If the app has no server-rendered HTML to reuse, use createRoot instead.
As an Amazon Associate I earn from qualifying purchases.
A mismatch is not merely cosmetic: React may need extra work to recover, and a serious mismatch can lead to event handlers being attached to the wrong elements. React’s guidance is to fix the differing output rather than rely on recovery.
Recommended Free Tools
Find the earliest divergence
- Reproduce it in development. Read the full warning, component stack, and mismatch details. If the only report is a minified production error, reproduce the problem with a development build; React’s error 418 page recommends local development debugging.
- Compare server HTML with the first client render. Inspect the raw response HTML and identify the earliest difference in text, attributes, or tree structure. Work outward from that point rather than changing the first component named in the warning without checking its output.
- Trace the value or branch that produced it. Check render-time conditions, data passed into the component, formatting, and markup. Then check whether anything outside React changed the delivered HTML or browser DOM.
- Change the source of the difference. Make the server and initial client render use the same data and deterministic output. Use an effect or client-only rendering only when the UI genuinely depends on browser state.
Common causes and what to inspect
Browser-only checks and APIs
A render branch such as typeof window !== 'undefined', or a value read from localStorage or the viewport, can select different markup on the server and client. Keep the initial render server-compatible, then read browser-only state after hydration if a later update is acceptable.
#1 Best Overall
Time, randomness, and locale formatting
Calls that depend on the current time or a random value can return different results across the two renders. Locale-sensitive date or number formatting can also differ between environments. Render a stable value shared by server and client, or defer the client-specific presentation until after hydration when that change is appropriate.
Different data snapshots
If the server rendered one data snapshot and the browser’s first render uses newer or otherwise different external data, the resulting content may not match. Pass the same initial snapshot to the client render; update to fresher data afterward if needed.
Invalid HTML nesting
Check the generated markup for invalid nesting, such as elements placed where the HTML parser restructures them. The browser may parse server HTML into a tree different from the one React expects. Next.js lists invalid nesting among its hydration error causes.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Changes outside the component
Browser extensions can modify the DOM, while a CDN or edge transformation can alter the HTML response. If the component’s output appears consistent, compare the server response before and after delivery and inspect the DOM before application code changes it. Next.js also documents CSS-in-JS configuration as a possible cause in its framework-specific troubleshooting guidance.
Choose a fix that matches the cause
| Approach | Does the initial output match? | Trade-off | Use it when |
|---|---|---|---|
| Make data and rendering deterministic | Yes, when server and client use the same initial values and logic | Addresses the underlying mismatch without requiring a second render | The cause is different data, a time- or random-dependent value, or environment-dependent formatting |
| Update browser-specific UI in an effect | Yes, if the server and first client render share a compatible initial state | Adds a render after hydration and can make the change feel jarring | The initial server-compatible UI is acceptable before browser state is applied |
| Render a component only on the client | The component does not need to hydrate from server-rendered markup | That component’s content is delayed until client rendering | The component truly requires browser-only rendering; the specific disabling-prerendering option is framework-dependent |
suppressHydrationWarning |
No; it does not make differing content match | Suppresses a warning only in a narrow scope | A local, unavoidable difference such as a timestamp remains after other causes have been ruled out |
React’s effect-based two-pass approach is appropriate only when the initial output is valid for both environments; the later update costs an additional render. The suppression option works one level deep and does not cause React to patch mismatched text. In Next.js, follow its page for framework-specific options such as disabling prerendering for a selected component; do not treat that as a universal React API.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use the current hydration API
For a server-rendered app, current React examples use hydrateRoot. React 19 removed the older ReactDOM.hydrate API; see the React 19 upgrade guide. The optional onRecoverableError callback can report errors React recovers from, along with error information; some errors may include an original cause. It can help surface production issues, but logging a recovery does not fix the mismatch.
For historical migration context, React’s React 18 upgrade guide discusses the transition to the modern root APIs. Use the current API reference for behavior and options.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
