Hydration failed because the initial UI does not match what was rendered on the server
Wrap the non-deterministic render in useEffect so the first client render matches the server HTML. Success looks like the console warning disappearing on reload. Applies to: Next.js 13+ (app or pages router), React 18+.
TL;DR
Wrap the non-deterministic render in useEffect so the first client render matches the server HTML. Success looks like the console warning disappearing on reload.
The exact error
Hydration failed because the initial UI does not match what was rendered on the serverSteps to fix
- Find the element the warning points at (the console names the mismatching tag)
- Move browser-only values like Date.now, Math.random, or window.innerWidth into a useEffect or a mounted flag
- Only if the difference is cosmetic and unavoidable, add suppressHydrationWarning to that element
- Rebuild and reload; the warning should be gone
When this applies
- Next.js app or pages router with SSR
- React prints the hydration mismatch warning in the console
When this does NOT apply
- Pure client-side React apps with no SSR
- Errors that crash the build instead of warning at runtime
Tool + versions
Next.js 13+ (app or pages router), React 18+
Why it happens
The HTML the server sent and the HTML React renders on the client for the first pass disagree. The usual cause is rendering something that only exists in the browser during SSR.
Edge cases
- Third-party widgets that inject their own markup
- React StrictMode double-invoking render in dev
- Browser extensions rewriting the DOM before React hydrates
Where this came from
Resolved from a real public thread: https://nextjs.org/docs/messages/react-hydration-error (docs:react-hydration-error).
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.