Hydration Mismatches Are a Message, Not a Bug
Date Published

A hydration mismatch means the HTML React generated on the server and the HTML it expected to generate in the browser disagree — often because something rendered differently depending on things only the browser knows: the current time, a random value, `window` width, locale-dependent formatting. The framework isn't confused; it's accurately reporting that the same code produced two different outputs.
The fix is almost never to suppress the warning. It's to find the actual source of the divergence and either move it to run only after hydration, or make it deterministic across both environments — a `useEffect`-gated value instead of one computed during render, for instance.
Ignoring it long enough tends to produce a specific, hard-to-diagnose failure mode: the page looks fine on first load, then something visibly flickers or reflows the moment React takes over, and the bug report that eventually shows up describes the symptom, not the cause.