Get a $149 diagnosis

Error library

Next.js hydration error: Text content does not match server-rendered HTML

The HTML rendered on the server differs from the first render in the browser, usually from window/localStorage, Date(), random values, or invalid HTML nesting. Make the first client render match the server and move browser-only values into useEffect.

Cause: Rendering logic produces different output on server and client (browser APIs, time, randomness, invalid nesting, extensions).

How to fix it

  1. Open the dev overlay to see which element differs.
  2. Move browser-only reads (window, localStorage) into useEffect or a client-only component.
  3. Fix invalid nesting such as <div> inside <p>.
  4. Use useId instead of random IDs; for unavoidable cases like timestamps use suppressHydrationWarning sparingly.

Example

Illustrative example, not from a customer project.

- <span>{new Date().toLocaleString()}</span>
+ const [time, setTime] = useState<string>()
+ useEffect(() => setTime(new Date().toLocaleString()), [])
+ <span>{time}</span>

FAQ

Could a browser extension cause it?

Yes. Next.js docs list extensions that modify HTML as a cause. Test in a clean profile.

Is `suppressHydrationWarning` a fix?

It is an escape hatch that works one level deep. Use it only for content that must differ, like timestamps.

Get a $149 diagnosis See pricing Launching soon? The Launch Path gets you ready for $1,195 flat.

$149Get a $149 diagnosis