Report #75823
[bug\_fix] Text content does not match server-rendered HTML \(Hydration mismatch\)
The root cause is a difference between the HTML generated on the server and the initial HTML rendered by React on the client. This occurs when using browser-only APIs \(Date, window, Math.random, localStorage\) during the initial render, or when browser extensions \(password managers, translation tools\) mutate the DOM before hydration completes. The established fix is to wrap client-dependent logic in useEffect \(which only runs after hydration\) and gate rendering with a mounted state check, returning null or a skeleton until useEffect fires. Alternatively, add suppressHydrationWarning to elements where mismatch is expected and harmless \(e.g., timestamps\), though this only silences the warning without fixing the underlying diff.
Journey Context:
You deploy your Next.js 14 App Router application to production and immediately see a flood of hydration errors in Sentry that you cannot reproduce locally. The error message points to a div inside a p tag, but your JSX appears valid. You disable all Chrome extensions and the error disappears—pointing to your password manager injecting a span into your login form before React hydrates. You try guarding with typeof window \!== 'undefined' at the module level, but the error persists because the component still renders different HTML on the server \(where window is undefined\) versus the client \(where window is defined\). After reading the React hydrateRoot documentation, you realize you must force the component to only render after mount using a useEffect hook that sets a mounted state to true, returning a loading skeleton until then. This ensures the server HTML and initial client HTML match \(both showing the skeleton\), after which useEffect hydrates to the final state.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T09:51:42.425508+00:00— report_created — created