React Error: Hydration Failed — What It Means & How to Fix It

What Does This Error Mean?

This error means the HTML that was generated on the server does not match what React expected to render on the client. Hydration is the process where React takes static HTML (from server-side rendering) and 'attaches' itself to it, making it interactive. If the HTML does not match, React cannot reuse it and has to throw an error or re-render everything from scratch.

Affected Models

React 16 and later with SSR
Next.js
Remix
Any server-side rendered React app

Common Causes

Rendering content that depends on the browser (like window.innerWidth or Date) which gives different results on server and client
Using Math.random() or Date.now() to generate content — the server and client will produce different values
Browser-specific HTML modifications by extensions (like ad blockers adding or removing elements)
Conditionally rendering based on whether code is running in a browser vs on the server without proper guards
Invalid HTML nesting — like putting a div inside a p tag — which browsers auto-correct differently

How to Fix It

Find the component mentioned in the error. Look for any values that might differ between server and client — dates, random numbers, window properties, or localStorage.

Next.js shows a helpful diff of the expected vs actual HTML. Use that to pinpoint the mismatch.
For browser-only content (like current time or window size), use a mounted state pattern: const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []); — only render the browser-specific content when mounted is true.

This renders nothing (or a placeholder) on the server and the real content on the client after mounting.
Never use Math.random() or Date.now() directly in JSX that is server-rendered. Either compute the value once and store it in state, or only show it after mounting.

If you need a unique ID during render, use a library like nanoid that is designed for SSR or React's useId hook (React 18+).
Check your HTML for invalid nesting. Block elements (div, p, ul) cannot be nested inside inline elements in certain combinations. The browser silently corrects this, but the correction differs between server and client.

Common mistake: a div inside a p tag. A paragraph (p) cannot contain block-level elements — the browser moves the div outside the p.
For elements where you know the server and client will always differ (like a 'last updated' timestamp), add suppressHydrationWarning={true} to that specific element.

Use this sparingly — only for cases where the mismatch is intentional and harmless.

When to Call a Professional

Hydration errors are usually fixable yourself. The key is to make sure your component renders the same HTML on both the server and the client. Use the suppressHydrationWarning attribute for intentional differences, or use useEffect to defer browser-only rendering.

Frequently Asked Questions

What is hydration and why does React need to do it?

When a page uses server-side rendering, the server sends fully-formed HTML to the browser. The browser can display it immediately — but it is static, with no interactivity. Hydration is when React runs in the browser and 'takes over' the existing HTML, attaching event listeners and making it interactive. React needs the HTML to match so it can attach to the right elements without re-creating everything.

My app works fine but I get this warning — should I fix it?

Yes — in React 17 it was a warning. In React 18 it is an error that causes a full re-render. A full re-render defeats the performance benefits of server-side rendering. It can also cause a flash of content as the client re-renders over the server HTML. Fix it for correctness and performance.

Does this error only happen with Next.js?

No — it happens with any server-side rendering setup: Next.js, Remix, Gatsby with SSR, or custom SSR. If you are using plain React with a client-side-only setup (Create React App), you will never see this error. The error is specific to the SSR + hydration workflow.