From 6d3924ef42a79f9a799914eb4caa448b046aee1e Mon Sep 17 00:00:00 2001 From: Yogayata Verma Date: Wed, 15 Apr 2026 15:24:39 +0530 Subject: [PATCH 1/4] docs(react-dom): add hydrateRoot hydration mismatch debugging guide --- .../reference/react-dom/client/hydrateRoot.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/content/reference/react-dom/client/hydrateRoot.md b/src/content/reference/react-dom/client/hydrateRoot.md index c48b6eb5196..c026fe1f8be 100644 --- a/src/content/reference/react-dom/client/hydrateRoot.md +++ b/src/content/reference/react-dom/client/hydrateRoot.md @@ -191,6 +191,7 @@ This is important for the user experience. The user will spend some time looking The most common causes leading to hydration errors include: * Extra whitespace (like newlines) around the React-generated HTML inside the root node. +* Using non-deterministic values like `Date.now()` or `Math.random()` in rendering logic. * Using checks like `typeof window !== 'undefined'` in your rendering logic. * Using browser-only APIs like [`window.matchMedia`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) in your rendering logic. * Rendering different data on the server and the client. @@ -531,3 +532,42 @@ root.render(App, {onUncaughtError}); // ✅ Correct: pass options to createRoot. const root = hydrateRoot(container, , {onUncaughtError}); ``` + +### Debugging hydration mismatches {/*debugging-hydration-mismatches*/} + +If you see an error like "Hydration failed because the server rendered HTML didn't match the client.", it means the HTML from the server is different from what React renders first in the browser. + + + +Uncaught Error: Hydration failed because the server rendered HTML didn't match the client. + + + +#### Common causes {/*common-causes*/} + +* Values that change every time you render, like `Math.random()` or `Date.now()`. +* Rendering that depends on browser-only globals like `window`, `document`, or `localStorage`. +* Different data on the server and the client during the first render. +* Data loading timing issues where server data and client data do not match. + +#### Example mismatch {/*example-mismatch*/} + +```js +function App() { + return
{Math.random()}
; +} +``` + +This renders a different value on the server and the client, so hydration fails. + +#### Debugging checklist {/*debugging-checklist*/} + +1. Open the browser console and find the first hydration warning. +2. Look for changing values in render (`Math.random()`, `Date.now()`). Move them to server data or calculate them after hydration in [`useEffect`.](/reference/react/useEffect) +3. Keep browser-only code out of render. Read `window`, `document`, and similar APIs in [`useEffect`](/reference/react/useEffect) or an event handler. +4. Make sure the first client render uses the same data as the server render. +5. If one mismatch is expected (for example, a timestamp), use `suppressHydrationWarning={true}` on that element. + +#### Isolating the component {/*isolating-the-component*/} + +If you still cannot find the issue, replace parts of the UI with simple static markup. Add components back one at a time until the warning comes back. The last part you added is usually where the mismatch is. From e4385c4ded301450b7d102a148989631f5e192a9 Mon Sep 17 00:00:00 2001 From: Yogayata Verma Date: Wed, 15 Apr 2026 15:43:59 +0530 Subject: [PATCH 2/4] docs(react-dom): mark intentional Math.random example with expectedErrors to fix markdown code-block lint failure --- src/content/reference/react-dom/client/hydrateRoot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react-dom/client/hydrateRoot.md b/src/content/reference/react-dom/client/hydrateRoot.md index c026fe1f8be..ba055e77432 100644 --- a/src/content/reference/react-dom/client/hydrateRoot.md +++ b/src/content/reference/react-dom/client/hydrateRoot.md @@ -552,7 +552,7 @@ Uncaught Error: Hydration failed because the server rendered HTML didn't match t #### Example mismatch {/*example-mismatch*/} -```js +```js {expectedErrors: {'react-compiler': [2]}} function App() { return
{Math.random()}
; } From e74f0c81c6f8e564c6f4efc664ca2b2673f3ac34 Mon Sep 17 00:00:00 2001 From: Yogayata Verma Date: Wed, 15 Apr 2026 15:46:04 +0530 Subject: [PATCH 3/4] docs(react-dom): clarify hydrateRoot checklist to reference hydration mismatch error and stack trace --- src/content/reference/react-dom/client/hydrateRoot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react-dom/client/hydrateRoot.md b/src/content/reference/react-dom/client/hydrateRoot.md index ba055e77432..3650963784f 100644 --- a/src/content/reference/react-dom/client/hydrateRoot.md +++ b/src/content/reference/react-dom/client/hydrateRoot.md @@ -562,7 +562,7 @@ This renders a different value on the server and the client, so hydration fails. #### Debugging checklist {/*debugging-checklist*/} -1. Open the browser console and find the first hydration warning. +1. Open the browser console and find the hydration mismatch message or error, and its stack trace. 2. Look for changing values in render (`Math.random()`, `Date.now()`). Move them to server data or calculate them after hydration in [`useEffect`.](/reference/react/useEffect) 3. Keep browser-only code out of render. Read `window`, `document`, and similar APIs in [`useEffect`](/reference/react/useEffect) or an event handler. 4. Make sure the first client render uses the same data as the server render. From 92948647682efaf53e3ede3218a669130bdc7321 Mon Sep 17 00:00:00 2001 From: YOGAYATA VERMA <63913693+yogayataverma@users.noreply.github.com> Date: Wed, 15 Apr 2026 15:46:45 +0530 Subject: [PATCH 4/4] Update src/content/reference/react-dom/client/hydrateRoot.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/content/reference/react-dom/client/hydrateRoot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react-dom/client/hydrateRoot.md b/src/content/reference/react-dom/client/hydrateRoot.md index 3650963784f..ec1e47d0eeb 100644 --- a/src/content/reference/react-dom/client/hydrateRoot.md +++ b/src/content/reference/react-dom/client/hydrateRoot.md @@ -563,7 +563,7 @@ This renders a different value on the server and the client, so hydration fails. #### Debugging checklist {/*debugging-checklist*/} 1. Open the browser console and find the hydration mismatch message or error, and its stack trace. -2. Look for changing values in render (`Math.random()`, `Date.now()`). Move them to server data or calculate them after hydration in [`useEffect`.](/reference/react/useEffect) +2. Look for changing values in render (`Math.random()`, `Date.now()`). Move them to server data or calculate them after hydration in [`useEffect`](/reference/react/useEffect). 3. Keep browser-only code out of render. Read `window`, `document`, and similar APIs in [`useEffect`](/reference/react/useEffect) or an event handler. 4. Make sure the first client render uses the same data as the server render. 5. If one mismatch is expected (for example, a timestamp), use `suppressHydrationWarning={true}` on that element.