Next.js Hydration Error: Causes and Fixes for Beginners (2026 Guide)

When a user visits a Next.js page: 1. **Server Rendering:** Next.js renders the React tree into raw HTML on the server and sends it to the browser for instant loading. 2. **Hydration:** The browser loads JavaScript, walks the existing HTML DOM, and attaches event listeners (clicks, inputs). If the HTML generated on the server differs from the initial render in the browser by even one character, React panics and throws: ```bash Error: Hydration failed because the initial UI does not match what was rendered on the server. Warning: Expected server HTML to contain a matching text content... ```

### 1. Rendering Dates or Timestamps Rendering `new Date().toLocaleTimeString()` produces one time on your server (UTC/NPT) and another time on the user's browser: **Fix:** Format dates after mounting with `useEffect`, or use `suppressHydrationWarning`: ```tsx {new Date(date).toLocaleDateString()} ``` ### 2. Reading localStorage or window on First Render Server has no `window` or `localStorage`, so reading them during render causes mismatches: **Fix:** Use an `isMounted` state pattern: ```tsx const [theme, setTheme] = useState("dark"); const [mounted, setMounted] = useState(false); useEffect(() => { setMounted(true); const saved = localStorage.getItem("theme"); if (saved) setTheme(saved); }, []); if (!mounted) return null; // or skeleton placeholder return ; ``` ### 3. Invalid HTML Tag Nesting Writing a `