iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A React hydration error means the HTML produced before the page became interactive does not match what React rendered on the client. The reliable fix is to find the first difference and make the server output and the client’s initial render agree—not just silence the warning.
What hydration expects
Hydration attaches React to HTML that was already generated in a server environment. React expects the initial client render to produce the same content and structure. If there is no server-rendered HTML to reuse, use createRoot rather than hydrateRoot. See React’s hydrateRoot reference.
React’s guidance is direct: “You should treat mismatches as bugs and fix them.” A recoverable mismatch is not necessarily harmless: recovery can slow the app, and in the worst case React may attach event handlers to the wrong elements. React’s upgrade guidance describes this risk.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsHow to find the first divergence
- Reproduce it in development. Read the warning’s component stack and mismatch details. If production shows only a minified error, reproduce locally with a development build; React’s error 418 explanation recommends this approach.
- Compare the server output with the first client render. Inspect the HTML returned by the server and the initial render in the browser. Trace the earliest difference in text, attributes, or tree structure; later warnings may be consequences of that first divergence.
- Inspect render-time values and branches. Search the affected component and its children for browser checks such as
typeof window, access tolocalStorage, viewport-dependent output, current time, random values, and locale-sensitive formatting. - Check the data snapshot. If the server rendered one version of data, the first client render must use that same version. A client that immediately renders newer external data can disagree with the HTML even when both outputs are valid on their own.
- Validate the final markup and delivery path. Check for invalid HTML nesting. In framework-rendered apps, also consider browser extensions, CSS-in-JS setup, and CDN or edge transformations that could change the response or DOM. The Next.js troubleshooting page lists these framework-specific causes.
Common causes and the matching fix
Browser-only state changes the initial render
A server cannot read browser state such as localStorage or the viewport. If a component uses that information during render to choose its initial markup, the server and client can produce different output. Keep the initial render server-compatible, then read browser-only state in an effect when a post-hydration change is acceptable. That approach adds another render and may cause a visible change, so it is not a substitute for matching initial output when the value can be supplied consistently.
#1 Best Overall
Time, randomness, or locale formatting varies
Values derived from the current time or randomness can differ between server and client. Locale-sensitive formatting can also vary with the environment. Prefer a stable value shared by both renders, or render a deterministic representation first and change it after hydration only if that experience is acceptable.
Server and client use different data
Pass the server-rendered data snapshot through to the initial client render instead of fetching or selecting a different value during the first render. If data must update, apply that update after hydration rather than letting it alter the initial markup.
HTML nesting or external changes alter the tree
Invalid nesting can be parsed into a DOM tree different from the structure React expects. Correct the markup rather than compensating in React. Also check whether an extension or delivery layer changes the HTML before React hydrates; a client-side fix will not address a response transformed outside the component.
Choose a remedy that fixes the cause
| Approach | Does the initial output match? | Trade-off |
|---|---|---|
| Make the initial data and render deterministic | Yes, when the same values and structure reach both renders | Fixes the underlying mismatch without requiring an extra client render. |
| Move browser-only work into an effect | Yes, if the initial server-compatible output is used first | Adds a render after hydration; the changed content can feel jarring. |
| Use a client-only component boundary | It avoids server-rendering that component | Appropriate only when the component genuinely must run in the browser; framework configuration is not a universal React API. |
suppressHydrationWarning |
No; it does not make the output match | Use only for an unavoidable local difference, such as a timestamp. It applies one level deep and does not cause React to patch mismatched text. |
For Next.js, the troubleshooting guide documents using useEffect, disabling prerendering for selected components, and suppressHydrationWarning as possible approaches. Treat those as framework guidance, and choose the option based on the actual cause rather than applying suppression broadly. Next.js hydration error guidance.
Use the current hydration API
Current React examples should use hydrateRoot(domNode, reactNode, options?) when hydrating server-generated markup. React 19 removed the older ReactDOM.hydrate API; the React 19 upgrade guide covers the change.
The optional onRecoverableError callback can observe errors React recovers from. It receives the error and error information; some errors may include an original cause. This can help surface recoveries in a production monitoring workflow, but logging does not itself correct mismatched output. API details are in the React reference.
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.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →
