JavaScript

Hydration Failed: What It Means and How to Fix It

Error reference

Hydration Failed

Language

JavaScript

Severity

High

When it happens

React 18's hydration error occurs when the HTML sent from the server does not match the component tree that React tries to render on the client.

Potential fixes

Defer dynamic content to a useEffect that runs only on the client. Use suppressHydrationWarning sparingly for truly intentional differences (like timestamps). Keep the initial render deterministic and identical on both server and client.

Deep dive

React 18's hydration error occurs when the HTML sent from the server does not match the component tree that React tries to render on the client. React expects the initial client render to be identical to the server render so it can 'adopt' the existing DOM nodes.

Why it happens

•Rendering dynamic values like new Date() or Math.random() that differ between server and client.
•Reading browser-only APIs like window or localStorage during the initial render.
•Rendering content based on cookies or auth state that differs between environments.
•Using a third-party component that is not SSR-safe.

Potential fixes

Defer dynamic content to a useEffect that runs only on the client. Use suppressHydrationWarning sparingly for truly intentional differences (like timestamps). Keep the initial render deterministic and identical on both server and client.

Examples

JavaScript

Code that triggers the error

function Timestamp() {
  // Different on server vs client
  return <p>{new Date().toLocaleTimeString()}</p>;
}

Error output

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Fixed code

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

function Timestamp() {
  const [time, setTime] = useState<string | null>(null);
  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
  }, []);
  return <p>{time ?? "Loading..."}</p>;
}

Practice in English

How would you explain a Hydration Failed to a fellow dev? Choose the right phrase:

"I hit an error...

Ready to practice your English at work?

Lingua-e has interactive exercises built around real developer conversations: standups, code reviews, retrospectives, and more. Practice until it comes naturally.

Try Lingua-e for free