What is hydration in Next.js and what causes a hydration error?

Q: What is hydration in Next.js and what causes a hydration error?

**Target Audience:** Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. **Difficulty:** Medium > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the **Verified** section, against real output from a build or a running server; each Verified block names the version it ran on. ## 1. Why This Even Matters — A Story First Imagine a painter who delivers a finished portrait, and an animator who arrives later to make it move. The animator draws their own version of the first frame and lays it over the painting. If the two match, they simply start animating the painting. If the painter showed the clock at 10:00:00 and the animator draws 10:00:07, the animator does not trust any of the painting any more, throws it away and paints the whole th

The problem

Question presented to candidate: "Users report a flash of different content and the console says hydration failed. What is hydration, what causes this error, and how do you fix it without hiding the bug?"

What a strong answer should cover:

Hydration is React attaching state and event handlers to HTML that the server already rendered, reusing the DOM instead of recreating it.
The first client render must produce exactly the same output as the server render; any difference is a mismatch.
Common causes: time and random values, typeof window branches, locale formatting, invalid HTML nesting, browser extensions changing the DOM.
On a mismatch React 19 discards the server HTML for that tree and re-renders on the client, which is slower and can flash.
Fixes: render the same value first and change it in an effect, use suppressHydrationWarning only for known cases such as timestamps, fix invalid nesting.

Clarifying questions expected:

"Does it happen for every user or only some?" — only some usually means extensions, locales or time zones.
"Is the mismatched value needed for the first paint?" — if not, render it after mount.

Code / implementation expected: Yes — a component that mismatches, and the corrected version.

nextjs
hydration
ssr
react

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. Difficulty: Medium

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the Verified section, against real output from a build or a running server; each Verified block names the version it ran on.

1. Why This Even Matters — A Story First

Imagine a painter who delivers a finished portrait, and an animator who arrives later to make it move. The animator draws their own version of the first frame and lays it over the painting. If the two match, they simply start animating the painting. If the painter showed the clock at 10:00:00 and the animator draws 10:00:

The solution is hidden so you can try first

7 min read · 8 sections

Read the code

A time value that mismatches, and the fixed version

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

// Mismatches: the server and the browser compute different times.
export function BadClock() {
  return <p>{new Date().toLocaleTimeString()}</p>;
}

// Fixed: the first render matches the server; the real value arrives after mount.
export function Clock() {
  const [time, setTime] = useState<string | null>(null);
  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
    const id = setInterval(() => setTime(new Date().toLocaleTimeString()), 1000);
    return () => clearInterval(id);
  }, []);
  return <p>{time ?? "--:--:--"}</p>;
}

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.