mui / mui/material-ui

Hydration error with mui icons in nextjs turbopack mode

Open
#46,181 2 comments 3 reactions 1 assignee View on GitHub

@Janpot is already working on this.

Since May 20, 2025.

nextjs scope: all components type: bug
Dominant language
JavaScript
Stars
99.1k
Forks
32.5k
Avg merge
2d 17h
Merged PRs (30d)
106

Description

Steps to reproduce

Steps:

  1. Check out the minimal repro: https://github.com/magnattic/mui-hydration-repro
  2. Run "yarn" and "yarn dev"
  3. Open localhost:3000
Current behavior

You will see the following hydration error in the console:

Image

Error log index.js:14 A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up. 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.

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

...
<PathnameContextProviderAdapter router={{sdc:{},sbc:{}, ...}} isAutoExport={true}>
<App pageProps={{}} Component={function Home} err={undefined} router={{sdc:{},sbc:{}, ...}}>
<AppCacheProvider err={undefined} router={{sdc:{},sbc:{}, ...}}>




<MuiCircularProgress-root className="MuiCircula..." style={{width:40,height:40}} ...>

<span

  •               className="MuiCircularProgress-root MuiCircularProgress-indeterminate MuiCircularProgress-colorPri..."

  •               className="MuiCircularProgress-root MuiCircularProgress-indeterminate MuiCircularProgress-colorPri..."
              style={{width:40,height:40}}
              role="progressbar"
            >
              <MuiCircularProgress-svg className="MuiCircula..." ownerState={{color:"pri...", ...}} ...>
                <Insertion>
                <svg

  •                   className="MuiCircularProgress-svg mui-54pwck-MuiCircularProgress-svg"

  •                   className="MuiCircularProgress-svg css-54pwck-MuiCircularProgress-svg"
                  viewBox="22 22 44 44"
                >
                  <MuiCircularProgress-circle className="MuiCircula..." style={{}} ...>
                    <Insertion>
                    <circle

  •                       className="MuiCircularProgress-circle MuiCircularProgress-circleIndeterminate mui-19t5dcl-..."

  •                       className="MuiCircularProgress-circle MuiCircularProgress-circleIndeterminate css-19t5dcl-..."
                      style={{}}
                      cx={44}
                      cy={44}
                      r={20.2}
                      fill="none"
                      strokeWidth={3.6}
                    >
...

overrideMethod @ hook.js:608
nextJsHandleConsoleError @ client.ts:57
(anonymous) @ react-dom-client.development.js:4621
runWithFiberInDEV @ react-dom-client.development.js:1519
emitPendingHydrationWarnings @ react-dom-client.development.js:4620
completeWork @ react-dom-client.development.js:11213
runWithFiberInDEV @ react-dom-client.development.js:1522
completeUnitOfWork @ react-dom-client.development.js:15268
performUnitOfWork @ react-dom-client.development.js:15149
workLoopSync @ react-dom-client.development.js:14956
renderRootSync @ react-dom-client.development.js:14936
performWorkOnRoot @ react-dom-client.development.js:14419
performWorkOnRootViaSchedulerTask @ react-dom-client.development.js:16216
performWorkUntilDeadline @ scheduler.development.js:45

exports.createElement @ react.development.js:1033
(anonymous) @ emotion-styled-base.browser.development.esm.js:156
MuiCircularProgress-circle @ emotion-element-489459f2.browser.development.esm.js:34
react-stack-bottom-frame @ react-dom-client.development.js:23863
renderWithHooksAgain @ react-dom-client.development.js:5629
renderWithHooks @ react-dom-client.development.js:5541
updateForwardRef @ react-dom-client.development.js:8645
beginWork @ react-dom-client.development.js:10861
runWithFiberInDEV @ react-dom-client.development.js:1519
performUnitOfWork @ react-dom-client.development.js:15132
workLoopSync @ react-dom-client.development.js:14956
renderRootSync @ react-dom-client.development.js:14936
performWorkOnRoot @ react-dom-client.development.js:14419
performWorkOnRootViaSchedulerTask @ react-dom-client.development.js:16216
performWorkUntilDeadline @ scheduler.development.js:45

exports.jsx @ react-jsx-runtime.development.js:339
CircularProgress @ CircularProgress.js:207
react-stack-bottom-frame @ react-dom-client.development.js:23863
renderWithHooksAgain @ react-dom-client.development.js:5629
renderWithHooks @ react-dom-client.development.js:5541
updateForwardRef @ react-dom-client.development.js:8645
beginWork @ react-dom-client.development.js:10861
runWithFiberInDEV @ react-dom-client.development.js:1519
performUnitOfWork @ react-dom-client.development.js:15132
workLoopSync @ react-dom-client.development.js:14956
renderRootSync @ react-dom-client.development.js:14936
performWorkOnRoot @ react-dom-client.development.js:14419
performWorkOnRootViaSchedulerTask @ react-dom-client.development.js:16216
performWorkUntilDeadline @ scheduler.development.js:45
<ForwardRef(CircularProgress)>
exports.jsxDEV @ react-jsx-dev-runtime.development.js:346
Home @ index.js:14
react-stack-bottom-frame @ react-dom-client.development.js:23863
renderWithHooksAgain @ react-dom-client.development.js:5629
renderWithHooks @ react-dom-client.development.js:5541
updateFunctionComponent @ react-dom-client.development.js:8897
beginWork @ react-dom-client.development.js:10522
runWithFiberInDEV @ react-dom-client.development.js:1519
performUnitOfWork @ react-dom-client.development.js:15132
workLoopSync @ react-dom-client.development.js:14956
renderRootSync @ react-dom-client.development.js:14936
performWorkOnRoot @ react-dom-client.development.js:14419
performWorkOnRootViaSchedulerTask @ react-dom-client.development.js:16216
performWorkUntilDeadline @ scheduler.development.js:45

exports.jsxDEV @ react-jsx-dev-runtime.development.js:346
App @ _app.js:7
react-stack-bottom-frame @ react-dom-client.development.js:23863
renderWithHooksAgain @ react-dom-client.development.js:5629
renderWithHooks @ react-dom-client.development.js:5541
updateFunctionComponent @ react-dom-client.development.js:8897
beginWork @ react-dom-client.development.js:10522
runWithFiberInDEV @ react-dom-client.development.js:1519
performUnitOfWork @ react-dom-client.development.js:15132
workLoopSync @ react-dom-client.development.js:14956
renderRootSync @ react-dom-client.development.js:14936
performWorkOnRoot @ react-dom-client.development.js:14419
performWorkOnRootViaSchedulerTask @ react-dom-client.development.js:16216
performWorkUntilDeadline @ scheduler.development.js:45

exports.jsx @ react-jsx-runtime.development.js:339
renderApp @ index.tsx:298
doRender @ index.tsx:787
render @ index.tsx:825
hydrate @ index.tsx:1003
await in hydrate
pageBootstrap @ page-bootstrap.ts:23
(anonymous) @ next-dev-turbopack.ts:49
Promise.then
[project]/node_modules/next/dist/client/next-dev-turbopack.js [client] (ecmascript) @ next-dev-turbopack.ts:28
(anonymous) @ dev-base.ts:201
runModuleExecutionHooks @ dev-base.ts:261
instantiateModule @ dev-base.ts:199
getOrInstantiateRuntimeModule @ dev-base.ts:97
registerChunk @ runtime-backend-dom.ts:85
await in registerChunk
registerChunk @ runtime-base.ts:356
(anonymous) @ dev-backend-dom.ts:127
(anonymous) @ dev-backend-dom.ts:127

Expected behavior

No hydration errors should occur.

Context

The issue seems to happen only in turbopack. When you run the same example without turbopack (yarn dev:noturbo), no errors happen.

My assumption is that the emotionCache settings are for some reason not properly applied to the mui icons on the server side. When I change the _document props to something like

const finalProps = await documentGetInitialProps(ctx, {
		emotionCache: createEmotionCache({ enableCssLayer: true, key: "my-key" }),
	});

the hydration warning stays the same, ie. the key is not applied.
If however I try the same without turbopack, I can clearly see the key being applied in the css classnames on the server side.

Your environment
npx @mui/envinfo 
    System:
    OS: Linux 5.15 Ubuntu 23.04 23.04 (Lunar Lobster)
  Binaries:
    Node: 20.8.1 - ~/.nvm/versions/node/v20.8.1/bin/node
    npm: 10.8.3 - ~/.nvm/versions/node/v20.8.1/bin/npm
    pnpm: Not Found
  Browsers:
    Chrome: 129.0.6668.89
  npmPackages:
    @emotion/react:  11.14.0
    @emotion/styled:  11.14.0
    @mui/core-downloads-tracker:  7.1.0
    @mui/icons-material: 7.1.0 => 7.1.0
    @mui/material: 7.1.0 => 7.1.0
    @mui/material-nextjs: ^7.1.0 => 7.1.0
    @mui/private-theming:  7.1.0
    @mui/styled-engine:  7.1.0
    @mui/system:  7.1.0
    @mui/types:  7.4.2
    @mui/utils:  7.1.0
    react: ^19.0.0 => 19.1.0
    react-dom: ^19.0.0 => 19.1.0

Search keywords: turbopack nextjs hydration AppCacheProvider

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.