Problem

You receive a red console compilation error: Error: Hydration failed because the initial UI does not match what was rendered on the server.

Symptoms

A brief flash of different text content or layout shifts on page load.
Console warnings pointing to HTML tags mismatches (e.g. Warning: Expected server HTML to contain a matching <div> in <body>).
Client-side event listeners fail to bind properly, making buttons unresponsive.

Root Cause

React Hydration is the process of attaching event listeners to static HTML rendered by the server (SSR). For hydration to succeed, the pre-rendered HTML generated by the server MUST match the initial DOM tree constructed by React on the client during page boot.

Mismatches occur when:

Invalid HTML Nesting: Writing elements inside tags that don't support them (e.g., nesting a block level <div> inside a paragraph <p> tag).
Deterministic Violations: Utilizing client-only values during initial render (e.g., window, localStorage, or random numbers like Math.random()).
Date Formats: Rendering raw timestamps like new Date().toLocaleTimeString() which differ depending on the server time and client browser timezone.

Quick Fix

Ensure client-only logic is wrapped inside a mounting hook:

// ❌ FAILS HYDRATION
export default function Timestamp() {
  return <span>Time: {new Date().toLocaleTimeString()}</span>
}

// ✔ SOLVES HYDRATION
import { useEffect, useState } from 'react'

export default function Timestamp() {
  const [mounted, setMounted] = useState(false)

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

  if (!mounted) {
    return <span>Time: Loading...</span>
  }

  return <span>Time: {new Date().toLocaleTimeString()}</span>
}

Prevention

Run static validations on markup nesting.
Configure suppressHydrationWarning on elements showing dynamic text that isn't critical (like local time stamps).
Use local-only state wrappers for local storage lookups.

Solving React Hydration Mismatch Errors

Problem

Symptoms

Root Cause

Quick Fix

Prevention