Hydration Mismatches and Debugging

When Server and Client Disagree

Hydration works because React trusts a fundamental contract: the server and client will produce identical output for the same input. When they don't, you get a hydration mismatch — one of the most frustrating bugs in SSR applications.

In development, React throws a loud warning. In production (before React 19), it silently patches the DOM, which can cause visual glitches, broken interactivity, or worse — the wrong content shown to users.

The Five Common Causes

1. Time-Dependent Values

The most frequent offender. The server renders at one point in time, the client hydrates at another.

function Greeting() {
  const hour = new Date().getHours()
  return <p>{hour < 12 ? 'Good morning' : 'Good evening'}</p>
}

If the server renders at 11:59 AM and the client hydrates at 12:01 PM, the server HTML says "Good morning" but the client expects "Good evening." Mismatch.

The fix: Defer time-dependent rendering to the client.

function Greeting() {
  const [greeting, setGreeting] = useState('Hello')

  useEffect(() => {
    const hour = new Date().getHours()
    setGreeting(hour < 12 ? 'Good morning' : 'Good evening')
  }, [])

  return <p>{greeting}</p>
}

The server and client both render "Hello" initially (match!), then useEffect updates to the correct greeting after hydration.

2. Random Values

function Banner() {
  const id = Math.random().toString(36).slice(2)
  return <div id={id}>Welcome!</div>
}

Math.random() produces different values on server and client. Always different. Always a mismatch.

The fix: Use useId() for stable identifiers.

import { useId } from 'react'

function Banner() {
  const id = useId()
  return <div id={id}>Welcome!</div>
}

useId generates deterministic IDs that are identical on server and client. It's specifically designed for this.

3. Browser-Only APIs

function Sidebar() {
  const width = window.innerWidth
  return width > 768 ? <DesktopSidebar /> : <MobileSidebar />
}

window doesn't exist on the server. This throws during SSR. Even if you guard it with a check, the server might render DesktopSidebar (no window = no width = fallback) while the client on a phone renders MobileSidebar.

The fix: Use a useEffect-based approach or CSS media queries.

function Sidebar() {
  const [isMobile, setIsMobile] = useState(false)

  useEffect(() => {
    setIsMobile(window.innerWidth <= 768)
  }, [])

  return isMobile ? <MobileSidebar /> : <DesktopSidebar />
}

Or better yet, use CSS to handle responsive layout — no JS needed, no mismatch possible:

function Sidebar() {
  return (
    <>
      <DesktopSidebar className="hidden md:block" />
      <MobileSidebar className="block md:hidden" />
    </>
  )
}

4. Locale and Environment Differences

function Price({ amount }) {
  return <span>{amount.toLocaleString()}</span>
}

toLocaleString() depends on the system locale. If your server runs in en-US but a user's browser is in de-DE, you get "1,234.56" vs "1.234,56." Mismatch.

The fix: Explicitly specify the locale.

function Price({ amount, locale = 'en-US' }) {
  return <span>{amount.toLocaleString(locale)}</span>
}

5. Invalid HTML Nesting

function Card() {
  return (
    <p>
      <div>This is invalid HTML nesting</div>
    </p>
  )
}

A <div> inside a <p> is invalid HTML. The browser's parser auto-corrects this by closing the <p> before the <div>, producing different DOM structure than React expects.

The fix: Use valid HTML nesting. <div> inside <p> is never correct — use <div> inside <div>, or <span> inside <p>.

How React Detects Mismatches

During hydration, React walks the server DOM and its virtual DOM simultaneously. At each node, it compares:

1. Element type — Is the server <div> what the client expects?
2. Text content — Does the text match?
3. Attributes — Do className, style, id, etc. match?

When a mismatch is detected:

Development mode: React logs a detailed warning to the console with a diff showing the expected vs actual HTML. In React 19, these warnings include improved error messages with the actual vs expected values side-by-side.

Production mode: Both React 18 and React 19 fall back to client-side rendering for the mismatched subtree. The key difference is error reporting: React 18 logged warnings in development but was less descriptive about what went wrong. React 19 provides significantly better error messages with actual-vs-expected diffs and is more tolerant of benign mismatches caused by browser extensions injecting extra tags. Both versions treat mismatches seriously — they were never truly "silent" in React 18, but the developer experience around diagnosing them has improved substantially in React 19.

The suppressHydrationWarning Escape Hatch

Sometimes a mismatch is intentional. The classic case: server timestamps.

function LastUpdated() {
  return (
    <time suppressHydrationWarning>
      {new Date().toLocaleTimeString()}
    </time>
  )
}

suppressHydrationWarning tells React: "I know this won't match. Don't warn me." React keeps the server HTML and doesn't patch it.

The Debugging Workflow

When you hit a hydration mismatch in development, follow this sequence:

Step 1: Read the error message. React 19 shows the expected vs received values. This often immediately reveals the cause.

Step 2: Identify what differs between server and client. The mismatch categories are:

• Time/date values → server and client run at different times
• Random values → Math.random(), crypto.randomUUID()
• Environment → window, navigator, localStorage, locale
• External data → APIs that return different results
• HTML structure → browser autocorrection of invalid nesting

Step 3: Apply the correct pattern.

function SafeClientValue({ fallback, children }) {
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
  }, [])

  if (!mounted) return fallback

  return children
}

function App() {
  return (
    <SafeClientValue fallback={<span>Loading...</span>}>
      <span>{window.innerWidth}px wide</span>
    </SafeClientValue>
  )
}

This pattern renders the fallback on both server and client (match!), then swaps to the real client content after hydration.

Step 4: Check your HTML validity. Use the W3C validator or React's development warnings. Invalid nesting is a silent killer — the browser "fixes" your HTML in ways React doesn't expect.

function TextField({ label }) {
  const id = useId()
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input id={id} type="text" />
    </div>
  )
}

Real Production Mismatch Examples

Example 1: Feature flags. A feature flag service returns true on the server (server-side evaluation) but the client JS hasn't loaded the flag yet. Components render differently.

Fix: Fetch flags on the server and pass them as props through the component tree, ensuring both server and client use the same flag values.

Example 2: User agent sniffing. Server detects "Mobile Safari" and renders a mobile layout. Client JS re-evaluates and also detects mobile — but the exact class names differ because of a conditional branch.

Fix: Don't use user agent for layout decisions. Use CSS media queries or useEffect-based client detection.

Example 3: Cached API responses. Server fetches from a stale cache, client fetches fresh data during hydration via useEffect. The initial render shows different content.

Fix: Use the same data source for both server and client initial render. Update with fresh data only after hydration via useEffect.