---
name: fix-react-hydration-errors
description: Finds and fixes React and Next.js hydration mismatch errors where server-rendered HTML differs from the first client render. Use when the console shows "Hydration failed", "Text content does not match server-rendered HTML", or content flickers or changes after the page loads.
license: CC-BY-4.0
metadata:
  category: debugging
  tags: "react,nextjs,ssr,hydration"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-30"
  status: published
---

# Fix React hydration errors

## When to use
- Next.js/Remix/any SSR React app logs a hydration mismatch warning or error.

## Steps
1. Read the diff React prints (React 19 shows the server vs client values); note the component.
2. Look for the usual causes in that component:
   - `Date.now()`, `new Date().toLocaleString()`, `Math.random()`, random IDs during render.
   - `window`, `localStorage`, `navigator` read during render.
   - Invalid nesting such as `<div>` inside `<p>`, or `<a>` inside `<a>`.
   - Browser extensions editing the DOM (test in a private window).
3. Fix by making the first client render match the server:
   - Move browser-only reads into `useEffect` and render a placeholder first.
   - Use `useId()` for IDs.
   - Format dates with a fixed locale/timezone, or render them client-only.
   - For whole widgets, `dynamic(() => import("./Widget"), { ssr: false })`.
4. Only for unavoidable one-element differences (e.g. a timestamp), add `suppressHydrationWarning` on that element.
5. Reload with the console open and confirm the warning is gone.

## Gotchas
- `typeof window !== "undefined"` checks inside render *cause* mismatches; they do not fix them.
- Theme classes set by a head script need `suppressHydrationWarning` on `<html>`.

## Example prompt
"Next.js keeps saying hydration failed because the text doesn't match."