Fix errors · How to use a skill

fix-react-hydration-errors

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.

Version 1.0 · Updated 2026-10-30

View raw SKILL.md

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-react-hydration-errors/raw' -o ~/'.claude/skills/fix-react-hydration-errors/SKILL.md'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-react-hydration-errors/raw' -o '.cursor/skills/fix-react-hydration-errors/SKILL.md'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-react-hydration-errors/raw' -o '.agents/skills/fix-react-hydration-errors/SKILL.md'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

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).
  1. 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 }).
  1. Only for unavoidable one-element differences (e.g. a timestamp), add suppressHydrationWarning on that element.
  2. 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."

Licence: CC BY 4.0. Attribution when you reuse it: From TheSkillVault, https://theskillvault.ai, CC BY 4.0