Mendlark / Guides

Next.js "Hydration failed because the server rendered HTML didn't match the client": how to fix it

Your Next.js app shows Hydration failed because the server rendered HTML didn't match the client, Text content does not match server-rendered HTML, or React error #418 or #423 in production. The page may flicker, lose its styling for a moment or stop responding to clicks. Here's what causes it in AI-built apps and how to fix each cause.

What's happening

Next.js builds each page's HTML on the server, then React runs in the browser and "hydrates" that HTML, attaching buttons and state to it. React expects the browser's first render to produce exactly the same HTML. When it doesn't, you get a hydration error and React throws away the server HTML and re-renders, which is the flicker you see. The Next.js docs on this error list the same causes as below.

1. Find the component

Run the app locally with npm run dev. In development, the error overlay shows a diff of the server and client HTML and names the component. Production builds only show a minified error number, so always reproduce locally first.

2. Dates, times and random values

The most common cause. new Date(), Date.now(), Math.random() or toLocaleString() give different results on the server (often in UTC) and in the visitor's browser. Render these only after the page has loaded:

'use client'
import { useEffect, useState } from 'react'

export function LocalTime({ iso }) {
  const [text, setText] = useState('')
  useEffect(() => {
    setText(new Date(iso).toLocaleString())
  }, [iso])
  return <time dateTime={iso}>{text}</time>
}

For a single timestamp you can't avoid, React allows suppressHydrationWarning on that one element. Don't spread it around to hide other problems.

3. Browser-only code during render

Code like typeof window !== 'undefined' ? ... : ..., or reading localStorage, window.innerWidth or a theme cookie while rendering, gives the server one answer and the browser another. Move it into useEffect as above. For a whole component that only makes sense in the browser, such as a map or a chart, load it without server rendering:

'use client'
import dynamic from 'next/dynamic'

const Map = dynamic(() => import('./Map'), { ssr: false })

In the App Router, ssr: false only works inside a Client Component, which is why the file starts with 'use client'.

4. Invalid HTML nesting

Browsers silently fix invalid HTML, so the browser's page no longer matches the server's. AI tools often produce these:

  • a <div> or another <p> inside a <p>
  • a <a> inside another <a> (a card link wrapping a button link)
  • a <button> inside a <button>
  • table rows without a <tbody>

Swap the outer <p> for a <div>, or restructure so links and buttons aren't nested.

5. Theme toggles and signed-in state

Dark-mode switches that read localStorage, and headers that show "Sign in" on the server but the user's name in the browser, both mismatch on first load. For themes, libraries such as next-themes handle this; put suppressHydrationWarning on the <html> tag as their docs say. For auth, read the session on the server (from cookies) so both sides agree, or show a neutral placeholder until the browser knows.

6. Browser extensions

Password managers, translators and ad blockers can change the page before React hydrates. If the error only appears in your normal browser and not in a private window with extensions off, it isn't your code. You can usually ignore it.

Quick checklist

  • Error reproduced with npm run dev and the component found
  • Dates, random values and locale formatting moved into useEffect
  • No window or localStorage reads during render
  • No <div> in <p>, no nested links or buttons
  • Theme and auth state agree on server and browser
  • Checked in a private window with extensions off

Still stuck?

Mendlark fixes this kind of problem for a fixed €49 (launch price, normally €79). We agree the problem first, test the fix and send it as a pull request, so nothing changes in your app until you merge it. If we can't fix it, you don't pay. Get the €49 fix, or start with a free scan.

Not sure what else is wrong? Paste your app link into the free instant check and get a plain-English list of problems in seconds.