Free tools Windows power users keep installed
One-click scans. No signup required.
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 Next.js hydration error means the page’s first browser render does not match the HTML Next.js generated on the server. Find and fix the source of that mismatch: the usual causes are invalid HTML, server-versus-browser rendering branches, unstable values, outside changes to the markup, and styling configuration errors.
Why am I getting a hydration error in Next.js?
Next.js sends prerendered HTML to the browser. React then hydrates that HTML by attaching event handlers and making the page interactive. For hydration to work, the initial browser render must agree with the server-rendered markup. If it does not, React can report a hydration error; depending on the mismatch, the page may also display unexpected content.
This applies to Client Components too: on an initial page load, Next.js prerenders them before the browser hydrates them. The 'use client' directive establishes a client/server module boundary; it does not, by itself, turn off prerendering. So adding it is not a general fix for mismatched output. Next.js: Server and Client Components.
Recommended Free Tools
What are the five common causes?
These five groupings are a practical way to troubleshoot, not an official Next.js taxonomy. Next.js documents several individual causes and examples. Next.js: Text content does not match server-rendered HTML.
#1 Best Overall
1. Broken HTML structure
Invalid nesting can lead the browser to parse the server’s HTML into a DOM tree that differs from the one React expects. Examples include putting a paragraph inside another paragraph, placing a <div> inside a paragraph, or nesting interactive elements in invalid ways.
Inspect the rendered elements and their nesting, not just the JSX’s indentation. Correct the markup so it is valid and produces the same structure in the browser as the server intended.
2. Server and browser take different branches
Render logic that checks typeof window !== 'undefined', or reads window or localStorage during rendering, can produce one result on the server and another in the browser. The first browser render must match the server HTML, even if you want the page to show browser-specific content afterward.
Rank #2
Keep the initial output consistent. If the browser-only value should appear after the page hydrates, read it in a useEffect and update the component then. If it is needed only in response to a user action, read it in an event handler instead.
3. Time or random values change between renders
A value based on the current time can differ between server rendering and the initial browser render. Random values can also cause mismatches, but the appropriate treatment depends on where they are generated: current Next.js documentation describes distinct prerendering constraints for Math.random() in Client and Server Components.
Decide what the value represents before choosing a fix. If it can be cached, use a stable value. If it must be generated per request in an applicable Server Component, Next.js documents using connection() to wait for request-time rendering. If it belongs only in the browser, defer it until after hydration. See the current guidance for the connection() function and prerendering with Math.random().
4. Something outside the component changes the markup
A browser extension can modify the page before React hydrates it. iOS can automatically turn phone numbers, email addresses, and other text into links. A CDN or edge feature, including Cloudflare Auto Minify, can also modify the HTML response.
To test for an extension-related change, compare behavior in a clean browser profile or with extensions disabled. For iOS’s automatic link detection, Next.js documents a format-detection meta tag option; use it when that behavior is the cause. Check CDN or edge HTML transformation settings if the response reaching the browser differs from the HTML your app generated.
5. CSS-in-JS setup is misconfigured
Next.js lists incorrectly configured CSS-in-JS libraries among possible hydration-error causes. Follow the current setup instructions for the specific library and the Next.js router you use. There is no single CSS-in-JS configuration that applies to every library.
How do I fix “Text content does not match server-rendered HTML”?
Start with the first mismatched element and trace the value or markup back to its source. Make the initial server and browser output equivalent unless the component genuinely needs to be browser-only.
- Find the mismatch. Use the error details to identify the element or text that differs, then inspect its rendered markup and the data used to produce it.
- Check the HTML structure. Fix invalid nesting and nested interactive elements before changing rendering behavior.
- Remove environment-dependent rendering. Do not select different initial output based on browser globals. Defer browser-dependent updates to an effect or event handler when appropriate.
- Stabilize changing values. Decide whether time or random data should be shared and cacheable, generated at request time, or shown only in the browser; choose a rendering approach that matches that requirement.
- Check for external changes. Test without extensions, review iOS link detection when relevant, and check whether a CDN or edge feature transforms the HTML.
- Verify styling-library setup. Apply the current Next.js integration instructions for the CSS-in-JS library in use.
- Use client-only rendering only for the component that needs it. If a component depends on a browser-only library, selectively disable prerendering rather than changing the whole route.
Which fix should I choose?
Choose based on whether the value needs to be present in the server HTML and whether the mismatch is being fixed or merely hidden.
| Approach | Use it when | What it changes |
|---|---|---|
| Make the initial output deterministic | The content should be available in server-rendered HTML. | Corrects the underlying mismatch by making server and first browser output agree. |
Update in useEffect or an event handler |
The value is browser-dependent and can appear after hydration or after user interaction. | Preserves matching initial output, then adds the browser-specific behavior. |
Use next/dynamic with ssr: false |
A particular component depends on a browser-only library and should not be prerendered. | Opts that component out of server rendering; it is a targeted option, not a blanket route fix. |
Use suppressHydrationWarning |
A narrow, unavoidable difference such as a timestamp remains. | Suppresses a warning at the affected level; it does not reconcile the differing values. |
Next.js documents selective client-only rendering with next/dynamic. In the App Router, ssr: false must be used from a Client Component.
When is suppressHydrationWarning appropriate?
Use it sparingly for a difference you cannot reasonably avoid, such as text that must reflect the current time. It works only one level deep. For mismatched text content at that level, React will not patch the text to make it agree. The warning is suppressed; the underlying values are not made consistent.
For a general repair, fix the source of the mismatch instead. Hiding the warning does not correct invalid markup, browser-dependent render branches, or changes made by an extension or CDN. Next.js documents the escape hatch and its limits.
Quick Recap
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.
