Skip to content
debugging

Diagnose and fix a Next.js hydration mismatch error

Walks an AI through correctly diagnosing a Next.js hydration mismatch and fixing the root cause, instead of silencing it with suppressHydrationWarning.

Who should use this

Is this prompt for you?

  • Developers seeing "Text content does not match server-rendered HTML" or similar hydration warnings
  • Anyone tempted to just add suppressHydrationWarning without understanding why the mismatch happens
  • Teams debugging inconsistent behavior between server and client renders in the App Router
The prompt

Copy this prompt

Prompt
I'm getting a Next.js hydration mismatch error. Help me find and fix the actual cause, not just suppress the warning.

Error message: [paste the exact error/warning text from the console]

Relevant code:
[paste the component(s) involved — include any that use Date, Math.random, window/document, localStorage, or conditionally render based on browser-only state]

Context: Next.js [version], App Router or Pages Router: [specify], rendering mode: [server component / client component / getServerSideProps, etc.]

Please:
1. Identify the specific source of non-determinism between server and client render — common causes are: use of Date/Math.random directly in render, reading window/localStorage/navigator during render, browser extensions injecting DOM, conditionally rendering based on typeof window, or mismatched data between server fetch and client fetch
2. Explain exactly why this particular code produces different output on server vs. client
3. Propose the correct fix for the actual cause — e.g. moving browser-only reads into useEffect, using a mounted-state guard, or making the value deterministic (like passing a server-generated timestamp as a prop instead of calling Date.now() in two places)
4. Do NOT propose suppressHydrationWarning as the fix unless the mismatch is truly unavoidable and cosmetic (e.g. a browser extension modifying the DOM) — if that's the case, say so explicitly and explain why
5. Show the corrected code
6. Suggest how to verify the fix (what to check in dev tools, and whether to test with JavaScript disabled to compare initial HTML)

Works well with Claude Code, Cursor and GitHub Copilot.

How to use it

Getting the best result

  1. 1Paste the exact console error text, including the component stack trace if shown
  2. 2Include every component in the tree that touches Date, random values, or browser-only globals
  3. 3Resist accepting suppressHydrationWarning as a first answer — ask "why does this mismatch happen" if offered
  4. 4Verify the fix by comparing server-rendered HTML (view source) against the hydrated DOM
Expected result

What you should get back

  • A clear explanation of exactly which value differs between server and client render
  • A root-cause fix (moving logic to useEffect, passing deterministic props, etc.) rather than a suppression flag
  • Corrected code with the mismatch source addressed
  • A verification method to confirm the fix actually resolved the mismatch
Tips

Get more out of this prompt

  • Dates, random IDs, and locale-formatted numbers are the most common hydration mismatch sources — check those first
  • If a third-party script or browser extension is the cause, suppressHydrationWarning on that specific element is legitimate — but say why
  • Test with browser extensions disabled to rule out DOM injection before assuming it's your code
Common mistakes

What to watch out for

  • Reaching for suppressHydrationWarning immediately instead of finding the actual non-deterministic value
  • Not including the full component tree, so the AI can't see where server and client data diverge
  • Fixing the symptom in one component while the same anti-pattern exists elsewhere in the codebase

Ready to put this prompt to work?

Pair it with an AI coding tool and a real project, then ship something this week.