---
title: "Hydration Mismatch"
slug: "hydration-mismatch"
category: "glossary"
tags: ["glossary", "frontend", "react", "ssr", "debugging", "rendering"]
status: "stable"
last_updated: 2026-05-14
summary: "A hydration mismatch occurs when server-rendered HTML differs from React's client render during hydration, causing a forced DOM replacement and console errors."
related:
  [
    "[[glossary/hydration]]",
    "[[glossary/ssr]]",
    "[[glossary/ssg]]",
    "[[frontend/react]]",
    "[[frontend/nextjs]]",
    "[[glossary/server-component]]",
  ]
---

## Overview

This page is the atomic definition. The hydration lifecycle is described at [[glossary/hydration]].

## Definition

A hydration mismatch occurs when React's client-side render of a component tree produces different HTML than the server sent. React compares its virtual tree against the actual DOM nodes. If they differ, React logs a warning (or in React 18, throws an error in strict mode) and falls back to a full client-side re-render of the mismatched subtree, discarding the server HTML. This defeats the performance benefit of [[glossary/ssr]] for affected components. Common causes: accessing `window`, `navigator`, or `localStorage` during render (these are undefined on the server); using `Date.now()` or `Math.random()` without a stable seed; rendering different markup based on authentication state that is only known client-side; browser extensions injecting DOM nodes; and locale or timezone differences between server and client. The fix is to defer environment-dependent logic to `useEffect` (which runs only on the client) or to use `suppressHydrationWarning` on elements whose content intentionally differs (such as timestamps). React Server Components ([[glossary/server-component]]) eliminate mismatch risk for their own output because they never hydrate.

## When it applies

Hydration mismatches appear in any Next.js or React application using [[glossary/ssr]] or [[glossary/ssg]] with client-side hydration. They do not apply to pure [[glossary/csr]] apps or to React Server Components.

## Example

```jsx
// Causes mismatch: renders different HTML on server vs client
function Clock() {
  return <time>{new Date().toLocaleTimeString()}</time>;
}

// Fixed: defer to client with useEffect
function Clock() {
  const [time, setTime] = useState("");
  useEffect(() => setTime(new Date().toLocaleTimeString()), []);
  return <time>{time}</time>;
}
```

## Related concepts

- [[glossary/hydration]] - the process that mismatches disrupt.
- [[glossary/ssr]] - SSR pages are the primary site of hydration mismatches.
- [[frontend/react]] - React 18 throws errors in strict mode for most mismatch types.
- [[frontend/nextjs]] - Next.js surfaces mismatch errors in the browser console and development overlay.
- [[glossary/server-component]] - Server Components avoid mismatches by never running on the client.

## Citing this term

> See [[glossary/hydration-mismatch|Hydration Mismatch]] (llmbestpractices.com/glossary/hydration-mismatch).

## Related

- [[glossary/hydration]]
- [[glossary/ssr]]
- [[glossary/ssg]]
- [[frontend/react]]
- [[frontend/nextjs]]
- [[glossary/server-component]]