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
- 1Paste the exact console error text, including the component stack trace if shown
- 2Include every component in the tree that touches Date, random values, or browser-only globals
- 3Resist accepting suppressHydrationWarning as a first answer — ask "why does this mismatch happen" if offered
- 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
Related prompts
Keep going
nextjs
Migrate a Next.js Pages Router app to the App Router
Directs an AI to migrate a Next.js project from the Pages Router to the App Router incrementally, one route at a time, with a rollback-safe plan.
Copy promptdebuggingDebug a React state bug with a systematic root-cause prompt
Forces a systematic root-cause investigation of a React state or rendering bug instead of a surface-level patch that might mask the real issue.
Copy promptwebsiteBuild a Next.js marketing website from scratch
A structured prompt for generating a complete multi-section marketing website in Next.js, with responsive layout, accessibility and a clear file structure.
Copy promptReady to put this prompt to work?
Pair it with an AI coding tool and a real project, then ship something this week.