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.0This 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)
- Upgrade the package that's complaining to a version that supports your setup:
npm install some-old-library@latest - If none exists, override the peer requirement in
package.json(see below). - As a last resort:
npm install --legacy-peer-deps
How to Read the Error
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 Xwhich 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@latestMost 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 installTest carefully: you're promising npm the combination works.
Fix 3: --legacy-peer-deps (Last Resort)
npm install --legacy-peer-depsThis 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--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:andCould not resolve ... from Xto identify the package - Check if a newer version of X supports your setup
- Use
overridesonly when you've confirmed compatibility - Use
--legacy-peer-depsas 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
- npm docs: npm install (legacy-peer-deps, force)
- npm docs: package.json overrides
- npm docs: config (legacy-peer-deps)
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.