Fix: Next.js Hydration Error (Text Content Mismatch)

The Error

You open your Next.js app and see something like:

Error: Hydration failed because the server rendered HTML didn't match the client.
As a result this tree will be regenerated on the client.

or in older versions:

Text content does not match server-rendered HTML.

Hydration is when React takes the HTML the server sent and attaches event handlers to it in the browser. To do that, React renders your components again in the browser and expects the exact same output. If anything differs, you get a hydration error.

🎯 Quick Fix

Find what renders differently on the server and the client:

1. Dates, times, random numbers → render them only after mount, or pass a fixed value from the server.
2. window, localStorage, navigator → read them in useEffect, not during render.
3. Invalid HTML nesting (<div> inside <p>) → fix the markup.
4. Browser extensions → test in an incognito window.

Why It Happens

The Common Causes and Fixes

1. Dates and Times

// ❌ different on server and client
{new Date().toLocaleTimeString()}

// ✅ render after mount
"use client";
import { useEffect, useState } from "react";

export function Clock() {
  const [time, setTime] = useState(null);
  useEffect(() => setTime(new Date().toLocaleTimeString()), []);
  return 
{time ?? "—"}
;
}

Time zones cause this too: the server may run in UTC while the user is in IST. Format dates with an explicit time zone, or format them on the client.

2. Random Values and IDs

Math.random() or crypto.randomUUID() during render gives different values each time. For element IDs, use React's useId(), which is stable between server and client.

3. Browser-Only APIs During Render

// ❌ window doesn't exist on the server
const isMobile = window.innerWidth < 768;

// ✅ read it after mount
const [isMobile, setIsMobile] = useState(false);
useEffect(() => setIsMobile(window.innerWidth < 768), []);

The same applies to localStorage (theme, cart), navigator and document.

4. Invalid HTML Nesting

Browsers "fix" invalid HTML before React sees it, so the structure changes:

5. Browser Extensions

Extensions like Grammarly, password managers and translators inject attributes or elements into the page before React hydrates. Test in an incognito window with extensions off. If the error disappears, it isn't your code. For attribute changes on <html> or <body>, you can add suppressHydrationWarning to those tags.

6. Theme or Auth Differences

Reading a dark-mode preference from localStorage during render shows "light" on the server and "dark" on the client. Use a cookie the server can read, or a library like next-themes that handles this.

7. Conditional Rendering on typeof window

// ❌ renders different trees on server and client
{typeof window !== "undefined" ?  : }

Use the useEffect mount pattern, or load the component client-only:

import dynamic from "next/dynamic";
const Map = dynamic(() => import("./Map"), { ssr: false }); // in a Client Component

{new Date().toLocaleString()}