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 FileNotFoundError Debugging Prompt
Debug Python FileNotFoundError from the exact traceback, resolved path, working directory, filesystem context, deployment environment, and failing operation.
Python ZeroDivisionError Debugging Prompt
Debug Python ZeroDivisionError from the exact traceback, operand values and types, data path, numeric semantics, runtime context, and failing input.
Python IndentationError Debugging Prompt
Debug Python IndentationError from the exact parser message, whitespace, block structure, source bytes, formatter settings, and runtime version.
Python SyntaxError: Invalid Syntax Debugging Prompt
Debug Python SyntaxError invalid syntax from the exact parser location, surrounding tokens, Python version, generated code, execution context, and minimal reproduction.
Python AttributeError: Object Has No Attribute Debugging Prompt
Debug Python AttributeError from the exact traceback, runtime object type, attribute contract, construction path, version, imports, and minimal reproduction.
Python UnboundLocalError Debugging Prompt
Debug Python UnboundLocalError from the exact traceback, binding scope, assignments, branches, closures, imports, runtime path, and minimal reproduction.