The Error

You run npm install and get a wall of red:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@19.1.0
npm ERR! node_modules/react
npm ERR!   react@"^19.1.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0 || ^18.0.0" from some-old-library@2.3.0

This is a peer dependency conflict. A package you're installing says "I only work with React 17 or 18," but your project uses React 19. Since npm 7, npm refuses to install conflicting peer dependencies instead of silently warning.


🎯 Quick Fix (In Order of Preference)

  1. Upgrade the package that's complaining to a version that supports your setup: npm install some-old-library@latest
  2. If none exists, override the peer requirement in package.json (see below).
  3. As a last resort: npm install --legacy-peer-deps

How to Read the Error

flowchart LR ROOT["Your project
react@19"] --> LIB["some-old-library@2.3.0"] LIB -.->|"peer: react ^17 or ^18"| X{"react 19
doesn't match"} X --> E["❌ ERESOLVE"]

The two key lines:

  • Found: what you have (react@19.1.0)
  • Could not resolve dependency: peer ... from X which package (X) wants something different

Now you know exactly which package to upgrade or replace.


Fix 1: Upgrade the Conflicting Package

npm view some-old-library peerDependencies   # what the latest version supports
npm install some-old-library@latest

Most popular libraries add support for new React, Next.js or ESLint versions within weeks. Check the library's changelog or GitHub issues.

Fix 2: Use overrides

If the library works fine with your version but hasn't updated its declared range, tell npm to use your version:

{
  "overrides": {
    "some-old-library": {
      "react": "$react",
      "react-dom": "$react-dom"
    }
  }
}

$react means "use the version from my root dependencies." Then:

rm -rf node_modules package-lock.json
npm install

Test carefully: you're promising npm the combination works.

Fix 3: --legacy-peer-deps (Last Resort)

npm install --legacy-peer-deps

This makes npm ignore peer dependencies entirely, like npm 6 did. It usually "works," but you lose the safety check, and real incompatibilities show up later as runtime bugs. If you use it, add it to .npmrc so the whole team and CI behave the same:

legacy-peer-deps=true
Avoid --force for this. It forces fetches and can install conflicting copies, hiding problems. Prefer upgrading, then overrides, then --legacy-peer-deps.

Common Real-World Cases

Conflict Usual fix
Library wants React 18, you're on React 19 Upgrade the library, or overrides if it's compatible
ESLint plugin wants an older ESLint Upgrade the plugin, or align ESLint versions
@types/* packages mismatch Align with your TypeScript and library versions
Old project after npx create-… Delete node_modules and lockfile, reinstall with current versions

Checklist

  • Read Found: and Could not resolve ... from X to identify the package
  • Check if a newer version of X supports your setup
  • Use overrides only when you've confirmed compatibility
  • Use --legacy-peer-deps as a documented last resort (in .npmrc)
  • Commit the updated package-lock.json
  • Run your tests and the app after changing dependencies

Frequently Asked Questions

What does ERESOLVE unable to resolve dependency tree mean?

It means npm found a peer dependency conflict: a package requires a version of another package, such as React, that doesn't match the version your project uses. Since npm 7, npm stops the install instead of ignoring the mismatch.

Is it safe to use --legacy-peer-deps?

It's often fine in practice, but it disables peer dependency checks, so real incompatibilities can appear later as runtime bugs. Prefer upgrading the conflicting package or using overrides after confirming compatibility, and document the flag in .npmrc if you need it.

What is the difference between --force and --legacy-peer-deps?

--legacy-peer-deps skips installing and checking peer dependencies, as npm 6 did. --force pushes past conflicts and other safeguards, which can result in conflicting package versions. For peer dependency errors, --legacy-peer-deps is the more targeted option.


Conclusion

ERESOLVE means a package's peer dependency range doesn't match your project. Identify the package from the error, upgrade it if possible, use overrides when you've confirmed it works with your versions, and keep --legacy-peer-deps as a documented last resort.


Sources

Last verified: 2 November 2026.


Related reads: Fix JavaScript Heap Out of Memory · Fix Next.js Hydration Error · Prisma vs Drizzle

I write practical guides for developers. Follow on LinkedIn or X, or invite me to speak.