Fix: npm ERESOLVE Error
Two packages need different versions of the same dependency. Here's how to fix it properly — without creating a broken dependency tree.
Last updated: October 2026
Try this first — it resolves 60% of cases without side effects:
npm install --legacy-peer-depsThis tells npm to ignore peer dependency conflicts and install anyway. Your packages resolve at runtime using whatever version is actually installed.
Then read the "Permanent fix" section below — --legacy-peer-deps is a band-aid, not a cure.
What ERESOLVE actually means
npm v7 changed how peer dependencies are installed. In older npm, missing or conflicting peer dependencies produced a warning and moved on. In npm v7+, they produce a hard error unless you explicitly allow it.
A "peer dependency" is a dependency a package declares but doesn't bundle — it expects YOU to provide it. Example: a React component library declares react as a peer dependency, meaning "I need React, but you're using it too, so we share it."
ERESOLVE happens when two packages each declare a peer dependency on the same package but require different versions:
Package A: needs react >= 17 < 19
Package B: needs react ^18.0.0
You have: react@19.0.0
→ npm can't find a version that satisfies both requirements
→ ERESOLVEWhy npm changed: Version 7 tried to be stricter about dependency conflicts because silent mismatches caused runtime bugs. In practice, many libraries declare overly strict peer requirements and work fine at runtime regardless. That's why --legacy-peer-deps exists.
Four fixes, from quickest to most correct
Quickest — use --legacy-peer-deps
Ignores peer conflicts and installs. Works 60% of the time, causes runtime problems 10% of the time. Use it to get unblocked, then plan a real fix.
# One-time fix
npm install --legacy-peer-deps
# Set as default for this project
# Add to .npmrc in the project root:
legacy-peer-deps=true
# Or install globally for all projects (last resort):
npm config set legacy-peer-deps trueCommit the .npmrc to your repo if you use this fix. Otherwise, CI and teammates will hit the same error without your workaround.
Slightly better — --force
Installs anyway, ignoring ALL version constraints — not just peer dependencies. More aggressive than --legacy-peer-deps. Use only when --legacy-peer-deps fails.
npm install --force--force can install broken trees. It doesn't check version constraints. Test thoroughly. If your app starts behaving strangely after install, this is why.
Recommended — read the error and resolve the conflict
The error output tells you exactly which packages conflict. Resolve the actual version mismatch:
# ERESOLVE error output tells you:
npm ERR! Could not resolve dependency:
npm ERR! peer react@">=17 <18" from some-library@1.2.3
npm ERR! node_modules/some-library
npm ERR! some-library@"*" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: react@18.3.1
npm ERR! peer react@"^18.0.0" from another-library@2.0.0
# Resolution options:
# 1. Upgrade some-library to a version that supports react@19
# → npm install some-library@latest
# 2. Or downgrade react to ^18
# → npm install react@18
# 3. Or replace one of the conflicting packages
# 4. Or force a specific version with overrides (see below)Best long-term — use overrides
Force a specific version across the whole dependency tree. This is npm's official mechanism for resolving conflicts and works in CI too.
// package.json
{
"overrides": {
"react": "18.3.1",
"some-library": {
"react": "18.3.1"
}
}
}
# Or force a specific sub-dependency
{
"overrides": {
"some-library": {
"another-library": "2.0.0"
}
}
}When to use overrides: When a package's peer requirement is wrong but the code actually works with the newer version. Overrides force the install without breaking the tree.
Real conflicts you'll hit (and their fixes)
| Conflict | Fix |
|---|---|
| React 19 + old React component library | --legacy-peer-deps then upgrade the library |
| TypeScript version mismatch (project vs peer) | Align TypeScript versions; use overrides if needed |
| ESLint 9 + ESLint plugins not updated yet | Stay on ESLint 8 until the plugin ecosystem catches up |
| Node version incompatibility | Switch Node with nvm/fnm; check package.json engines field |
| Peer package doesn't exist (renamed/removed) | Fork the package or find a maintained alternative |
🛡️ How to prevent ERESOLVE
- Keep dependencies updated regularly. Most ERESOLVE happens because one package is several majors behind.
- Use a lockfile and commit it.
package-lock.jsonpins exact versions so installs are reproducible. - Prefer packages with active maintenance. Look at the last update date and open issue count on npm.
- Read peer dependencies before installing.
npm info package-name peerDependenciesshows what a package expects. - Use
overridesinstead of--legacy-peer-depswhen you can. Overrides are checked into your project and work everywhere. - Test installs in a fresh clone. Run
rm -rf node_modules package-lock.json && npm installto catch issues before CI does.
❓ Frequently asked questions
What does npm ERESOLVE mean?
ERESOLVE means npm can't find a compatible version of a peer dependency that satisfies every package's requirements. Two or more packages need different versions of the same dependency, and npm can't reconcile them.
Should I use --legacy-peer-deps or --force to fix ERESOLVE?
--legacy-peer-deps is safer: it ignores peer dependency conflicts and installs anyway, letting packages resolve at runtime. --force is more aggressive and can install broken dependency trees. Use --legacy-peer-deps as a temporary fix, then resolve the root cause.
How do I fix ERESOLVE permanently?
Identify which two packages have conflicting peer requirements by reading the error output. Then: upgrade one of them, downgrade the other, replace one with an alternative, or add an overrides field in package.json to force a single version.
What is the overrides field in package.json?
;overrides lets you force a specific version of a dependency for all packages that depend on it. Example: 'overrides': { 'react': '18.2.0' } forces every package to use React 18.2.0, resolving conflicts at the resolution level.
Does ERESOLVE break my code?
Not directly — the install just fails. But if you use --force and end up with a broken dependency tree, your code may fail at runtime. Always test after forcing an install.