npm ERR! Peer Dependency Conflict— Fixed [Complete Guide 2026]
⚡ Quickest Fix — works 90% of the time
Add --legacy-peer-deps to your install command:
npm install --legacy-peer-depsStill broken? Every other fix is below — in order of what works fastest.
What Is a Peer Dependency Conflict?
A peer dependency conflict happens when two packages in your project require incompatible versions of the same dependency. The most common example: your project uses React 18, but a package you are installing declares it only supports React 17 as a peer.
npm 7 and above made peer dependency resolution strict — it throws a hard error instead of silently installing the wrong version like npm 6 did. This is why the error suddenly appeared after upgrading npm.
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@18.2.0
npm ERR! node_modules/react
npm ERR! react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-package@2.1.0
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-depsHow to Read the Error
| Line | What it means |
|---|---|
| Found: react@18.2.0 | The version you currently have installed |
| peer react@"^17.0.0" from some-package@2.1.0 | The version the conflicting package needs |
| Could not resolve dependency | npm cannot find a version that satisfies both requirements |
Run npm install --verbose to see the full dependency tree and identify exactly which package chain is creating the conflict.
Use --legacy-peer-deps
Works 90% of the timeThis flag tells npm to use the old npm 6 behaviour — it ignores peer dependency conflicts and installs anyway. Most of the time packages work fine together despite the version mismatch in their declared peer requirements.
npm install --legacy-peer-depsInstalling a specific package with the flag
npm install some-package --legacy-peer-depsWith npm ci (CI/CD pipelines)
npm ci --legacy-peer-depsIf this works, add legacy-peer-deps=true to your .npmrc file (see Fix 4) so you never need to type the flag again — and so CI/CD pipelines use it automatically.
Use --force
When --legacy-peer-deps does not workForce install bypasses all conflict checks and installs whatever npm can resolve. Use this only if --legacy-peer-deps did not fix it.
npm install --forcenpm install some-package --forceUsing --force can install genuinely incompatible versions that crash at runtime rather than install time. Always smoke-test your app thoroughly after a forced install before committing or deploying.
Update the Conflicting Package
Clean long-term fixThe cleanest solution is updating the package causing the conflict to a version that supports your current React, Node, or other dependency version. Many packages lag behind in their peer dependency declarations but newer versions have caught up.
Check what the package needs
npm info some-package peerDependenciesUpdate to latest version
npm install some-package@latestCheck all outdated packages at once
npm outdatedUpdate all packages to latest compatible versions
npx npm-check-updates -u
npm installnpx npm-check-updates -u updates all version numbers in package.json to the latest. Run npm install after to apply the updates.
Add to .npmrc Permanently
Team-wide fix for projects with known conflictsIf your project consistently needs --legacy-peer-deps, adding it to .npmrc means every developer and every CI/CD pipeline uses it automatically — no flags to remember or forget.
Create or edit .npmrc in your project root
legacy-peer-deps=trueAfter saving, plain npm install works without any flags:
npm install # automatically uses legacy-peer-depsCommit .npmrc to git
git add .npmrc
git commit -m 'chore: set legacy-peer-deps for npm install'You can also set this globally for all your projects: npm config set legacy-peer-deps true — but project-level .npmrc is better practice as it only affects the project that needs it.
Downgrade Your Dependency
When the conflicting package has no newer versionIf the conflicting package has not released a version that supports your React or Node version yet, the only clean option is downgrading your own dependency to what the package expects. This is less common but sometimes necessary with older packages that are no longer actively maintained.
Check what version the package requires
npm info some-package peerDependencies
# Output example:
# { react: '^17.0.0' }Downgrade React to match (example)
npm install react@17 react-dom@17Downgrading React or other core dependencies will affect every other package in your project. Always check what else depends on the version you are downgrading before making this change.
How to Prevent Peer Dependency Conflicts
- Run npm outdated regularly to catch version drift before it becomes a conflict
- Check peer dependencies before installing: npm info package-name peerDependencies
- Add legacy-peer-deps=true to .npmrc for projects with many dependencies
- Keep React, Next.js, and other core dependencies up to date
- Use npm install --dry-run to preview what will change before installing
- Consider switching to pnpm which has more flexible peer dependency handling
Quick Reference — Fix Order
- 1npm install --legacy-peer-deps90%
- 2npm install --force95%
- 3Update conflicting package to latest97%
- 4Add legacy-peer-deps=true to .npmrc99%
- 5Downgrade your own dependency to match99.9%
Frequently Asked Questions
What does npm peer dependency conflict mean?+−
Is --legacy-peer-deps safe to use?+−
What is the difference between --legacy-peer-deps and --force?+−
Why did peer dependency errors suddenly appear after upgrading npm?+−
How do I check what peer dependencies a package needs?+−
Can I add --legacy-peer-deps to package.json permanently?+−
Need Expert Help?
We Build Production-Grade Next.js & Node.js Apps
Softplix is a full-stack development agency. Struggling with npm issues in a production project? We can help fix your setup and ship faster.
Talk to an Engineer