Fix guides / Next.js "Hydration failed" error

How to fix the Next.js "Hydration failed" error

Next.js shows a red overlay saying hydration failed because the server rendered HTML did not match the client. The page may still look fine, but parts can break or flicker. Here are the usual causes.

What hydration is

Next.js renders your page to HTML on the server, then React attaches to that HTML in the browser. If the browser's first render produces different HTML, React reports a hydration mismatch.

Cause 1: values that differ between server and browser

new Date(), Math.random(), Date.now(), or toLocaleString() give different results on the server and in the browser. Render them after mount:

'use client';
import { useEffect, useState } from 'react';
export function Clock() {
  const [now, setNow] = useState(null);
  useEffect(() => setNow(new Date().toLocaleTimeString()), []);
  return <span>{now ?? ''}</span>;
}

Cause 2: checking window or localStorage during render

Code like typeof window !== 'undefined' ? A : B renders B on the server and A in the browser. Move browser-only reads into useEffect, or load the component client-only:

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

Note: ssr: false must be used inside a Client Component in the App Router.

Cause 3: invalid HTML nesting

A <div> inside a <p>, a link inside a link, or a <table> without <tbody>. The browser silently repairs the HTML, so it no longer matches. The overlay in recent Next.js versions points at the offending element; change the outer p to a div.

Cause 4: browser extensions

Extensions such as password managers or translators inject attributes into the page. Test in a private window with extensions off. If the error disappears, it is not your code. For attributes added to <html> or <body>, suppressHydrationWarning on that element is acceptable.

Do not just silence it everywhere

suppressHydrationWarning only works one level deep and hides real bugs. Fix the cause where you can.

Last updated 2026-10-19.