How do I fix 'Hydration failed because the initial UI does not match' in Next.js?

Hydration compares the HTML from the server with what React renders first in the browser. Any difference triggers this error.

Common causes

1. Non-deterministic values in render: Date.now(), new Date().toLocaleString(), Math.random(), crypto.randomUUID().
2. Browser-only checks: typeof window !== "undefined" ? a : b inside render.
3. Invalid HTML nesting: <div> inside <p>, <a> inside <a>, <tr> directly in <table> without <tbody> in some cases.
4. Browser extensions that inject attributes (dark mode, translation, password managers).
5. localStorage or cookies read during the first render.

Fixes

Render the same thing first, then update after mount:

"use client";
import { useEffect, useState } from "react";

export function LocalTime({ iso }: { iso: string }) {
  const [text, setText] = useState(iso);
  useEffect(() => {
    setText(new Date(iso).toLocaleString());
  }, [iso]);
  return <time dateTime={iso}>{text}</time>;
}

For unavoidable single-element mismatches (a timestamp) you can add suppressHydrationWarning to that element only. It works one level deep and does not fix real structure mismatches.

For client-only widgets use next/dynamic with ssr: false inside a client component.

Debugging

React 19 prints a diff of the mismatching tree in the console, so read it rather than just the headline. Test in a private window with extensions disabled. Also check the HTML nesting by viewing page source.

Pitfall: setting theme from localStorage in render causes this for dark mode. Use a small inline script plus CSS variables, or next-themes, which handles it.