Next.js "hydration failed" or text does not match the server HTML? The documented causes and the safe order of fixes

What hydration is and what a mismatch means

A Next.js page is first rendered to HTML on the server so it appears quickly. React in the browser then hydrates it: it renders the same component tree again and attaches event handlers to the existing HTML. For that to work, the first browser render must produce exactly what the server produced. Next.js describes the error as a difference between the React tree prerendered on the server and the one rendered during the first render in the browser. React's documentation says to treat mismatches as bugs and fix them. It is not only cosmetic: React notes that, at best, recovery slows the page, and at worst event handlers attach to the wrong elements, which is a functional fault.

• The error text usually names a text or attribute difference.
• It may appear only in development, only in production or only for some visitors.

The documented causes

Next.js lists these as common causes, in no stated order of frequency. Invalid HTML nesting, such as a paragraph inside a paragraph, a division inside a paragraph, a link inside a link or a button inside a button, because the browser repairs the HTML before React sees it. Rendering that differs between server and browser: a typeof window check, or use of window or localStorage, in the render; or time-dependent values such as the Date constructor, so the server's time and locale differ from the visitor's. Browser extensions that modify the HTML. A misconfigured CSS-in-JS library. An edge or content network that rewrites the HTML response, such as an automatic minify option. And on iOS, automatic detection of phone numbers and similar text and conversion to links.

• Search your components for new Date, window, localStorage and navigator in render code.
• Validate the HTML structure of the failing component.
• Test in a clean browser profile without extensions.
• Check whether a content network or host option alters HTML.

Fix the cause before silencing the warning

Three documented fixes exist and have costs. A client-only effect: render the server-matching output first and switch after an effect sets a flag. It works, but React warns it makes hydration slower because components render twice, and the visible change after load can feel abrupt on slow connections. Disabling server rendering for one component with a dynamic import removes it from the server HTML. And suppressHydrationWarning silences one element, for something that inevitably differs such as a timestamp; React says it works only one level deep, is an escape hatch, and does not patch the mismatched text. It hides the symptom, not the difference.

• Use a stable value for rendered dates, such as a formatted string from the server with an explicit time zone and locale.
• Move browser-only reads into effects.
• Do not wrap large areas in suppressHydrationWarning.

A safe first investigation

Reproduce in a development build, where React prints a diff, and in a production build, where the message is shorter. Note whether it depends on locale or time zone by changing both in the browser. Bisect by removing components from the page until the error stops. Check the rendered server HTML (view source) against what the browser shows after load. Do not send customer data; the error text and the component name are enough to decide.

• Error depends on time or locale: a date or number format is the cause.
• Error disappears without extensions: an extension is the cause for that user, not your code.
• Error appears only on one host: look at the edge or CDN.

What fixes it and how the paid job is accepted

A hydration fault is a reproducible defect, so it fits our bug-fix job with a failing-then-passing regression test (posted test price from £295, untested): a test that renders the page and fails with the mismatch on the old code, and passes after, with the page loading without hydration warnings in the agreed browsers, locales and time zones. If the real symptom is a blank screen when data fails, that is the separate states job (posted test price £245). Neither covers third-party scripts you will not change. Send the error text, the framework version and the page in your first enquiry, not source code or customer data.