Skip to content

[Fiber] Explain hydration errors better #33683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+150 −55
Open

[Fiber] Explain hydration errors better #33683

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc4af90
[Fiber] Less coloquial copy for hydration errors
vercel-release-bot Jul 2, 2025
bfa57af
Add diff explainer
eps1lon Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions packages/react-dom/src/__tests__/ReactDOMFizzForm-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ describe('ReactDOMFizzForm', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\n' +
'It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n\n' +
'It can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n\n' +
'https://react.dev/link/hydration-mismatch\n\n' +
' <App isClient={true}>\n' +
' <form\n' +
Expand Down Expand Up @@ -391,7 +391,7 @@ describe('ReactDOMFizzForm', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\n' +
'It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n\n' +
'It can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n\n' +
'https://react.dev/link/hydration-mismatch\n\n' +
' <App>\n' +
' <form\n' +
Expand Down
2 changes: 1 addition & 1 deletion packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10235,7 +10235,7 @@ describe('ReactDOMFizzServer', () => {
'\n- External changing data without sending a snapshot of it along with the HTML.' +
'\n- Invalid HTML tag nesting.' +
'\n' +
'\nIt can also happen if the client has a browser extension installed which messes with the HTML before React loaded.' +
'\nIt can also happen if the client has a browser extension installed which changes the HTML before React loaded.' +
'\n' +
'\nhttps://react.dev/link/hydration-mismatch' +
'\n' +
Expand Down
76 changes: 38 additions & 38 deletions packages/react-dom/src/__tests__/ReactDOMHydrationDiff-test.js
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion packages/react-dom/src/__tests__/ReactDOMRoot-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ describe('ReactDOMRoot', () => {
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n' +
'\n' +
'It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n' +
'It can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down
2 changes: 1 addition & 1 deletion packages/react-dom/src/__tests__/ReactDOMSingletonComponents-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -559,7 +559,7 @@ describe('ReactDOM HostSingleton', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension installed ' +
'which messes with the HTML before React loaded.\n' +
'which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down
2 changes: 1 addition & 1 deletion packages/react-dom/src/__tests__/ReactDOMSrcObject-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ describe('ReactDOMSrcObject', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\n' +
'It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n\n' +
'It can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n\n' +
'https://react.dev/link/hydration-mismatch\n\n' +
' <img\n' +
'+ src={Blob:image/jpeg}\n' +
Expand Down
2 changes: 1 addition & 1 deletion packages/react-dom/src/__tests__/ReactDOMUseId-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -708,7 +708,7 @@ describe('useId', () => {
- 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.
It can also happen if the client has a browser extension installed which changes the HTML before React loaded.

https://react.dev/link/hydration-mismatch

Expand Down
2 changes: 1 addition & 1 deletion packages/react-dom/src/__tests__/ReactRenderDocument-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ describe('rendering React components at document', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension ' +
'installed which messes with the HTML before React loaded.\n' +
'installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down
10 changes: 5 additions & 5 deletions packages/react-dom/src/__tests__/ReactServerRenderingHydration-test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ describe('ReactDOMServerHydration', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension ' +
'installed which messes with the HTML before React loaded.\n' +
'installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down Expand Up @@ -264,7 +264,7 @@ describe('ReactDOMServerHydration', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension ' +
'installed which messes with the HTML before React loaded.\n' +
'installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down Expand Up @@ -304,7 +304,7 @@ describe('ReactDOMServerHydration', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension ' +
'installed which messes with the HTML before React loaded.\n' +
'installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down Expand Up @@ -370,7 +370,7 @@ describe('ReactDOMServerHydration', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension ' +
'installed which messes with the HTML before React loaded.\n' +
'installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down Expand Up @@ -642,7 +642,7 @@ describe('ReactDOMServerHydration', () => {
"- Date formatting in a user's locale which doesn't match the server.\n" +
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension ' +
'installed which messes with the HTML before React loaded.\n' +
'installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch\n' +
'\n' +
Expand Down
4 changes: 2 additions & 2 deletions packages/react-reconciler/src/ReactFiberHydrationContext.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -393,7 +393,7 @@ function throwOnHydrationMismatch(fiber: Fiber, fromText: boolean = false) {
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n' +
'\n' +
'It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n' +
'It can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n' +
'\n' +
'https://react.dev/link/hydration-mismatch' +
diff,
Expand Down Expand Up @@ -888,7 +888,7 @@ export function emitPendingHydrationWarnings() {
'- External changing data without sending a snapshot of it along with the HTML.\n' +
'- Invalid HTML tag nesting.\n' +
'\n' +
'It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n' +
'It can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n' +
'\n' +
'%s%s',
'https://react.dev/link/hydration-mismatch',
Expand Down
2 changes: 1 addition & 1 deletion scripts/error-codes/codes.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -403,7 +403,7 @@
"415": "Error parsing the data. It's probably an error code or network corruption.",
"416": "This environment don't support binary chunks.",
"417": "React currently only supports piping to one writable stream.",
"418": "Hydration failed because the server rendered %s 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:\n\n- A server/client branch `if (typeof window !== 'undefined')`.\n- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.\n- Date formatting in a user's locale which doesn't match the server.\n- External changing data without sending a snapshot of it along with the HTML.\n- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension installed which messes with the HTML before React loaded.\n\nhttps://react.dev/link/hydration-mismatch%s",
"418": "Hydration failed because the server rendered %s 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:\n\n- A server/client branch `if (typeof window !== 'undefined')`.\n- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.\n- Date formatting in a user's locale which doesn't match the server.\n- External changing data without sending a snapshot of it along with the HTML.\n- Invalid HTML tag nesting.\n\nIt can also happen if the client has a browser extension installed which changes the HTML before React loaded.\n\nhttps://react.dev/link/hydration-mismatch%s",
"419": "The server could not finish this Suspense boundary, likely due to an error during server rendering. Switched to client rendering.",
"420": "ServerContext: %s already defined",
"421": "This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition.",
Expand Down
Loading