Common causes of hydration errors

The common causes of hydration errors have one thing in common: the first browser render does not match the server HTML. Find the changed value or element, then open the matching cause guide below for a fix.

All common causes of hydration errors

hydration-proof links each finding to a likely cause guide:

What React lists as the causes

React 19 includes a list of possible causes in its error message:

Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:
 
- A server/client branch `if (typeof window !== 'undefined')`.
- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.
- Date formatting in a user's locale which doesn't match the server.
- External changing data without sending a snapshot of it along with the HTML.
- Invalid HTML tag nesting.
 
It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.

React's list is not exhaustive. CSS-in-JS class names and suppressed differences can also matter.

How hydration-proof picks a cause

The report suggests a cause using four kinds of evidence:

1. The two values. Millisecond timestamps, the same number with different separators, random decimals and UUIDs, class names that look generated (sc-, css-, emotion-), theme classes (dark, light), React ids and whitespace-only differences each point at one cause.
2. The code near the line. hydration-proof maps the element to your source file and scans the component that rendered it for Date.now(), localStorage, matchMedia, fetch, typeof window and similar calls. Code in a neighboring component never explains a finding.
3. The scenario. A browser timezone or locale that differs from the server's, dark mode, a mobile viewport or pre-filled storage.
4. The stage. Markup the browser's parser repaired is invalid nesting. A change between parsing and hydration came from a script or an extension. A form the server rendered with Server Action state is form state. A difference on an element with suppressHydrationWarning is intentional.

The report shows its confidence and the supporting reason. When confidence is too low, it does not name a cause. A browser branch such as typeof window is easier to identify in a development build with source locations. See how it works.

Prove the cause with probes

Use --probe to test a suggested cause. It reloads the page while changing one browser factor at a time:

If a single change moves or removes the finding, the report marks that factor as proven. If identical reloads differ, inspect server or API data instead. See probes for the details.

npx hydration-proof test --probe

Causes, ESLint rules and issue codes

The ESLint plugin catches many risky patterns in source code. The browser check finds differences that a linter cannot see. Each cause guide links to its relevant rules. The confidence values below come from the package's production-build fixtures; they are not a promise for every app.

browser-api scores lower because the values alone never show it: the cause comes from the code, which is exact in development builds and depends on source maps in production.

Related

• React hydration errors explained
• Every React hydration error message, decoded
• All hydration-proof issue codes
• The 15 ESLint rules
• Proving a cause with probes