Next.js Hydration Error Debugging Prompt
Debug a Next.js hydration error from the exact server HTML, first client render, component boundary, versions, console output, and minimal reproduction.
Prompt Template
You are a senior Next.js and React engineer helping me diagnose a hydration error from evidence. Compare the server-rendered HTML with the first client render at the smallest failing component boundary. Work from the exact framework and runtime versions, router, rendering mode, console message, component code, props, data path, locale, time zone, browser, extensions, and minimal reproduction I provide. Distinguish invalid HTML nesting, nondeterministic render values, browser-only APIs, server/client branches, locale or time formatting, stale or changing data, external-store initialization, CSS-in-JS ordering, third-party DOM mutation, extension injection, and an error that occurs after hydration. Never invent rendered markup, package behavior, network output, component ownership, or a successful fix. Do not hide the warning with suppression, disable server rendering broadly, move the whole page to the client, or add a mounted-state workaround until the mismatch and tradeoff are proved. Next.js, React, Node.js, package-manager, and browser versions: [details] Router and rendering mode: [App Router or Pages Router; static, dynamic, streamed, other] Exact development and production launch commands: [paste] Complete browser and server console output with component stack: [paste sanitized] Smallest failing component and its parent boundary: [paste] Server component, client component, dynamic import, and Suspense boundaries: [details] Props, fetched data, cache or revalidation settings, and serialization path: [details] Captured server HTML for the failing region: [paste] Captured first client render or DOM snapshot before effects: [paste] Date, time, locale, random, ID, viewport, storage, media-query, and browser-API usage: [details] External stores, CSS-in-JS, UI libraries, analytics, scripts, and extensions: [details] Whether it reproduces in a clean browser, production build, and minimal route: [results] Recent dependency, rendering, data, locale, or markup changes: [details] Security, accessibility, SEO, performance, and browser-support constraints: [details] Provide: 1. A concise mismatch classification tied to the first divergent server and client node. 2. An evidence table separating confirmed server output, first client output, later effects, assumptions, and unknowns. 3. A render timeline from server evaluation through HTML delivery, client initialization, hydration, layout and passive effects, and later mutations. 4. Safe instrumentation or read-only checks to capture deterministic inputs and isolate the smallest failing boundary. 5. A ranked root-cause list with each hypothesis linked to observed markup, data, environment, or timing evidence. 6. The smallest reversible fix for the best-supported cause, with exact component scope and why server and first-client output now match. 7. Separate remedies for invalid nesting, nondeterministic values, browser-only state, locale differences, unstable IDs, stale data, third-party mutation, and extension interference where relevant. 8. Verification in a clean browser using both development and production builds, with the original route, no hydration warning, matching initial markup, and preserved behavior. 9. Regression protection through a focused test, deterministic fixture, lint or markup check, and server/client snapshot comparison where practical. 10. Rollback steps, remaining unknowns, and the next single artifact to collect if the mismatch is not proved. Redact tokens, cookies, personal data, internal hostnames, and proprietary payloads. Use hydration-warning suppression only for a narrow, intentional, documented mismatch whose accessibility and SEO effects are understood, never as the diagnosis.
Example Output
Current Diagnosis
The supplied snapshots first diverge at `[component boundary]`: the server renders `[server value]`, while the first client render produces `[client value]` before any effect runs. That supports a nondeterministic initial-render input; it does not yet prove which source created it.
Isolation Checks
1. Capture the value and its source on the server and during the first client render.
2. Replace it temporarily with one deterministic fixture inside the smallest boundary.
3. Rebuild and test the same route in a clean browser with extensions disabled.
4. Compare the server HTML and pre-effect client tree again.
Minimal Fix Shape
Derive the initial value from one serialized server input, then update browser-specific state after hydration only if the UI requires it. Keep the boundary server-rendered unless evidence shows otherwise.
Verify
Run development and production builds, confirm identical initial markup and no hydration warning, then check accessibility, SEO-visible content, and the original interaction.
Tips for Best Results
- ๐กCapture both the server HTML and the first client render before effects; the later DOM can hide where the mismatch began.
- ๐กList every date, locale, random, ID, storage, viewport, and browser-only value used during render because one unstable input is enough.
- ๐กTest a production build in a clean browser before blaming framework code; extensions and development-only behavior can mutate the page.
Frequently Asked Questions
What is the Next.js Hydration Error Debugging Prompt prompt?
Debug a Next.js hydration error from the exact server HTML, first client render, component boundary, versions, console output, and minimal reproduction. It's a free ChatGPT prompt template from our Coding collection โ copy it, fill in the bracketed variables, and paste it into your AI tool.
Which AI tools work with this prompt?
It's written and tested for ChatGPT, Claude and Gemini. Any AI assistant that accepts free-form text prompts will handle it well.
How do I customize this ChatGPT prompt?
Replace the bracketed variables โ such as [details], [paste], [paste sanitized] โ with your own details before running it. Capture both the server HTML and the first client render before effects; the later DOM can hide where the mismatch began.
Is this prompt free to use?
Yes. Every prompt on PromptAtlas is free to copy, customize, and use โ no signup required.
Related Prompts
Python ModuleNotFoundError Debugging Prompt
Debug Python ModuleNotFoundError from the exact traceback, interpreter, environment, import path, project layout, packaging metadata, and launch command.
Segmentation Fault Debugging Prompt
Debug a segmentation fault from the exact crash signal, source, build flags, backtrace, sanitizer evidence, inputs, and runtime environment.
CORS Error Debugging Prompt
Debug a CORS error from the exact browser message, origins, preflight exchange, server stack, proxy path, credentials mode, and response headers.
CLAUDE.md Generator Prompt
Generate a concise CLAUDE.md repository instruction file from verified project commands, conventions, boundaries, and existing documentation.
GitHub Actions Workflow Generator Prompt
Generate a minimal GitHub Actions workflow from verified repository commands, events, runner needs, permissions, secrets, caching, and deployment constraints.
Docker Command Generator Prompt
Generate a precise Docker CLI command from your goal, environment, current container state, version, and safety constraints.