Hydration failed ⚛️ React

Error: Hydration failed because the initial UI does not match what was rendered on the server

The HTML rendered on the server differs from the first client render, so React (Next.js/Remix) can’t attach to it.

Seen on: React

Meaning

Server-side rendering requires the first client render to produce identical markup. Values that differ between server and browser — dates, random IDs, window/localStorage, locale formatting — or invalid HTML nesting cause mismatches.

Common causes

  • Rendering Date.now(), Math.random() or locale-dependent formatting
  • Reading window, localStorage or media queries during render
  • Invalid nesting (<div> inside <p>, <a> inside <a>)
  • Browser extensions modifying the DOM
  • Different data on server vs client

⚡ Quick fix

  1. Move browser-only values into useEffect (render a placeholder first)
  2. Fix invalid HTML nesting
  3. Use suppressHydrationWarning only for unavoidable text like timestamps
  4. Render client-only components with dynamic(() => import(...), { ssr: false }) in Next.js

Detailed fix by platform

React

  1. Client-only value after mount:
    jsx
    function LocalTime({ iso }) {
  const [text, setText] = useState('');               // same on server and first client render
  useEffect(() => setText(new Date(iso).toLocaleString()), [iso]);
  return <time dateTime={iso}>{text}</time>;
}

How to diagnose

  1. Diff — Which text/element differs (dev overlay shows it)?
  2. Browser APIs — window/localStorage/Date used in render?
  3. HTML — Invalid nesting?
  4. Extensions — Reproduce in a clean profile

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.