What causes hydration mismatches, and how should you debug them?

Direct answer

A hydration mismatch occurs when the client's initial render does not produce the same structure or text as the server HTML, so debug the first render for environment-dependent or nondeterministic output rather than treating the warning as cosmetic.

Nondeterministic values: timestamps, random numbers, locale differences, or unstable IDs generated independently on server and client.
Browser-only branching: rendering different JSX because window, localStorage, or viewport data exists only on the client.
Data mismatch: the client hydrates using different initial data from the data used to generate server HTML.
Invalid markup: browser HTML correction can change the DOM structure before React hydrates it.

Prefer making the initial server and client outputs identical. If something truly cannot match, isolate the difference instead of broadly suppressing hydration warnings.