Fix npm "ERESOLVE unable to resolve dependency tree"

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

Common causes

• A library declares a peer dependency on an older major version, such as react ^17 while the project uses React 18 or 19
• Upgrading a framework (Angular, React, ESLint, Webpack) before its plugins support the new version
• Two packages requiring incompatible versions of the same peer
• An old package-lock.json created by npm 6, which did not enforce peer dependencies
• A package that is no longer maintained and never updated its peer ranges

How to fix it

1. Read the conflict lines. Look for 'Found: [email protected]' and 'Could not resolve dependency: peer react@"^17.0.0" from [email protected]'. That tells you some-lib is the package that needs updating or replacing.
2. Upgrade the conflicting package. Run npm view some-lib peerDependencies and npm view some-lib versions to find a release that supports your version, then npm install some-lib@latest.
3. Inspect the installed tree. Run npm ls react (or the peer named in the error) to see which packages pull in which versions. This shows whether one or several packages are behind.
4. Use legacy peer deps as a workaround. Run npm install --legacy-peer-deps to ignore peer conflicts like npm 6 did. To make it stick for the team, add legacy-peer-deps=true to the project .npmrc, and test that the package actually works.
5. Override a dependency version. Add an overrides section in package.json to force a specific version for a nested dependency. Use this when you have verified the newer version works with that package.
6. Regenerate the lock file. If the conflict came from an old lock file, delete node_modules and package-lock.json, run npm install, and commit the new lock file after testing.

package.json / .npmrc

// package.json - force a nested version
{
  "overrides": {
    "some-lib": {
      "react": "$react"
    }
  }
}

# .npmrc - workaround shared with the team
legacy-peer-deps=true

How to stop it happening again

• Check plugin compatibility before upgrading a framework's major version
• Commit package-lock.json and use npm ci in CI
• Prefer actively maintained packages that keep peer ranges current
• Run npm outdated regularly and upgrade in small steps