How to Fix Next.js hydration mismatch

What this error means

Next.js rendered HTML on the server, but when React hydrated it on the client the DOM didn't match. React tears the page down and re-renders, so users see a flash and any client-only state is lost.

Why this happens

Common causes: rendering `Date.now()` or `Math.random()` directly in JSX, reading `window` without a guard, conditional rendering based on `localStorage`, or an HTML structural issue (block element inside an inline element).

Quick fix (for end users)

• Open the browser console and read the warning — it shows the exact element that didn't match.
• Avoid using `new Date()` or random values directly in render.

Admin / engineer fix

• Wrap any client-only rendering in `useEffect` so it runs after hydration.

  commandCopy

  const [isMounted, setIsMounted] = useState(false);
  useEffect(() => setIsMounted(true), []);
  if (!isMounted) return null;

• If you need different SSR vs client output, use `dynamic` with `{ ssr: false }`.

  commandCopy

  import dynamic from 'next/dynamic';
  const ClientOnly = dynamic(() => import('./ClientOnly'), { ssr: false });

• Check for invalid HTML nesting — `<p>` containing `<div>`, etc.

Step-by-step fix

1. 1

   Reproduce in development; the warning names the offending element.

2. 2

   Identify the source of the mismatch (date, random, browser API, invalid nesting).

3. 3

   Move client-only rendering into useEffect or use dynamic import with ssr: false.

Common variations of this error

People also see these phrasings of the same problem:

• Text content does not match server-rendered HTML
• React hydration failed

Still broken? Try these

• If a third-party component is causing it, wrap it in a dynamic import with ssr: false.
• If using browser extensions during testing, some inject DOM nodes — try in clean profile.
• Theme/dark-mode toggles are a common offender; persist via cookie not localStorage so SSR and client agree.

Related errors

• Vercel
  Vercel build fails with TypeScript 'Type error'
• Vercel
  Vercel build failed (generic)

Related searches

• next.js hydration warning
• react hydration mismatch fix

Frequently asked questions