Fix a Next.js hydration mismatch caused by changing initial markup

A page loads but React reports that the server-rendered content does not match the browser’s first render. The warning can accompany flicker or unexpected event behaviour.

Why this happens

The initial server and client trees differ. Common triggers include rendering the current time, random values or browser-only state directly during the initial render.

Step-by-step solution

1. Read the mismatch details and isolate the smallest component that differs. Check invalid HTML nesting as well as dynamic values.

2. Render a deterministic initial state on both sides. Move browser-only reads into an effect or a deliberately client-only component where appropriate.

3. Pass stable server-generated values as props when they belong in the initial HTML. Avoid using warning suppression to conceal a structural mismatch.

Worked example

A saved theme read from localStorage cannot be read by the server. Use a consistent initial render and then apply the browser preference through the application’s chosen theme strategy.

Verify the fix

Hard-refresh the page and test both saved-preference and first-visit cases. Confirm the console is clear and the page remains usable before client-side effects finish.

Prevent a repeat

Include server-rendered pages in smoke tests. Avoid Date.now() and Math.random() in markup that must match across server and browser renders.

Reference

Official documentation or standards guidance

An original Gistmax troubleshooting guide. Scenarios and sample values are illustrative; configuration depends on your software version and environment. Cover diagram: Gistmax Tutorials.