Fix an AI-generated React hydration error: server and browser output must agree

A worked example: where the task becomes difficult

A fictional article page displays “Good morning” using the server’s timezone during rendering and the visitor’s timezone in the browser. It also reads a saved theme before the initial client output. The visual differences can create a hydration mismatch. Record the conflicting element and initial values; do not assume every mismatch comes from the same library or that the entire page must become client-only.

Decisions to make before implementation

Classify information as deterministic at initial rendering or dependent on the visitor’s environment. Choose a consistent initial representation for time and preferences, then update intentionally after the browser is ready. Validate element nesting and third-party markup. Preserve accessible content and document meaning; removing server rendering solely to silence a warning can introduce unnecessary loading and discovery tradeoffs.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Capture the first mismatch and identify its owning component.
• Compare initial server and browser values for the affected output.
• Use a deterministic initial state or isolate genuinely client-only behavior.
• Retest a clean page load, returning preference state and navigation between routes.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Investigate the first hydration mismatch in the article header. Compare server and initial browser output for date, greeting and theme. Preserve the page’s server-rendered article. Repair deterministic initialization or invalid markup at the owning component. Do not suppress every warning. Report the tested clean-load and saved-preference cases.

Failure modes that an attractive preview can hide

Warning suppression can be appropriate for a deliberately understood difference, but it should not conceal arbitrary invalid markup or render loops. Avoid replacing all dates with client-only spinners. Another source may be an extension changing the document; reproduce in a controlled browser profile before attributing that change to your source code.

Technical references: Chrome: console features reference

Acceptance checks and the evidence to retain

Keep the mismatch evidence, rendering contract and checked states. Explain any intentional remaining differences rather than treating an empty console as the only success condition.

Specific answers

Common questions