Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

npm refuses to install @material-ui/core 4 next to a newer React

Errornpm error code ERESOLVE

Short answer

Material UI v4 declares peer React versions up to 17, so npm 7+ stops when your app uses a newer React. The lasting fix is upgrading to @mui/material (v5 and later), the only line that fully supports React 18. Use the official codemod for the renames instead of editing every import by hand.

  • Applies to npm 10, @mui/material 6, React 19, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List what pulls in the old package, so you know whether your code or a library asks for it.

    npm ls @material-ui/core react
  2. 2Match what you see, then jump to its fix

    1. 1npm ls shows @material-ui/core as a direct dependency of your appYour own code still imports @material-ui/coreFix
    2. 2Imports of makeStyles or withStyles from the old packageYou still use makeStyles or withStylesFix
    3. 3ERESOLVE names @material-ui/icons or @material-ui/labIcons or lab packages are still on the old namesFix

What does the error look like?

  • npm error code ERESOLVE
  • Could not resolve dependency: peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4

Cause 1 of 3

Your own code still imports @material-ui/core

1Check

The migration guide says v5 requires React 17 or later and is the only version that fully supports React 18.

grep -rln "@material-ui/" src/ | head

2Fix

Install the v5 packages, run the official codemod on your source folder, then remove the old packages.

npm install @mui/material @emotion/react @emotion/styled
npx @mui/codemod@latest v5.0.0/preset-safe src
npm uninstall @material-ui/core

3Verify

A clean install passes and the app builds.

npm install
npm run build

Confirmed by mui.com

Did this fix it?

Cause 2 of 3

You still use makeStyles or withStyles

1Check

The guide describes @mui/styles as the deprecated JSS-based package that lets you keep makeStyles and withStyles while migrating. It requires a ThemeProvider at the app root.

grep -rn "makeStyles\|withStyles" src/ | head

2Fix

Install @mui/styles as a stop-gap, wrap the app in ThemeProvider, and move components to the newer styling API afterwards.

npm install @mui/styles

3Verify

The app renders and the styled components keep their look.

npm run dev

Confirmed by mui.com

Did this fix it?

Cause 3 of 3

Icons or lab packages are still on the old names

1Check

Each v4 package has a renamed successor in the guide, for example icons and lab.

npm ls @material-ui/icons @material-ui/lab

2Fix

Install the renamed packages and let the codemod rewrite the imports.

npm install @mui/icons-material @mui/lab
npm uninstall @material-ui/icons @material-ui/lab

3Verify

No @material-ui package is left in the tree.

npm ls | grep material-ui

Confirmed by mui.com

Did this fix it?

How do I stop it coming back?

  • Commit package-lock.json so a CI install resolves the same tree.
  • Check the peer range of a UI library before you upgrade React.
  • Do the MUI upgrade on its own branch, with the app building before and after.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.