npmNode.jsError Fix2026 Updated

npm ERR! Peer Dependency Conflict— Fixed [Complete Guide 2026]

January 20265 min readnpm 7–10 · All OS

⚡ Quickest Fix — works 90% of the time

Add --legacy-peer-deps to your install command:

npm install --legacy-peer-deps

Still 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.

Terminal Error
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-deps

How to Read the Error

LineWhat it means
Found: react@18.2.0The version you currently have installed
peer react@"^17.0.0" from some-package@2.1.0The version the conflicting package needs
Could not resolve dependencynpm 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.

1

Use --legacy-peer-deps

Works 90% of the time
30 sec

This 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.

terminal
npm install --legacy-peer-deps

Installing a specific package with the flag

terminal
npm install some-package --legacy-peer-deps

With npm ci (CI/CD pipelines)

terminal
npm ci --legacy-peer-deps

If 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.

2

Use --force

When --legacy-peer-deps does not work
30 sec

Force install bypasses all conflict checks and installs whatever npm can resolve. Use this only if --legacy-peer-deps did not fix it.

terminal
npm install --force
terminal
npm install some-package --force

Using --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.

3

Update the Conflicting Package

Clean long-term fix
2 min

The 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

terminal
npm info some-package peerDependencies

Update to latest version

terminal
npm install some-package@latest

Check all outdated packages at once

terminal
npm outdated

Update all packages to latest compatible versions

terminal
npx npm-check-updates -u
npm install

npx npm-check-updates -u updates all version numbers in package.json to the latest. Run npm install after to apply the updates.

4

Add to .npmrc Permanently

Team-wide fix for projects with known conflicts
1 min

If 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

.npmrc
legacy-peer-deps=true

After saving, plain npm install works without any flags:

terminal
npm install   # automatically uses legacy-peer-deps

Commit .npmrc to git

terminal
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.

5

Downgrade Your Dependency

When the conflicting package has no newer version
3 min

If 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

terminal
npm info some-package peerDependencies
# Output example:
# { react: '^17.0.0' }

Downgrade React to match (example)

terminal
npm install react@17 react-dom@17

Downgrading 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

Quick Reference — Fix Order

  1. 1npm install --legacy-peer-deps90%
  2. 2npm install --force95%
  3. 3Update conflicting package to latest97%
  4. 4Add legacy-peer-deps=true to .npmrc99%
  5. 5Downgrade your own dependency to match99.9%

Frequently Asked Questions

What does npm peer dependency conflict mean?+
It means two packages in your project require incompatible versions of the same dependency. npm 7+ throws this as a hard error instead of silently installing the wrong version like npm 6 did.
Is --legacy-peer-deps safe to use?+
Usually yes. It tells npm to use the old npm 6 behaviour which installed packages despite peer conflicts. Most packages work fine even with mismatched peer dependency declarations. Used by millions of projects.
What is the difference between --legacy-peer-deps and --force?+
--legacy-peer-deps ignores peer dependency version mismatches but still resolves the dependency tree. --force bypasses all conflict checks entirely. Use --legacy-peer-deps first — it is safer.
Why did peer dependency errors suddenly appear after upgrading npm?+
npm 7 changed peer dependency resolution from permissive to strict. If you upgraded from npm 6 to npm 7+, conflicts that were previously silent are now hard errors.
How do I check what peer dependencies a package needs?+
Run: npm info package-name peerDependencies. This shows exactly which versions the package requires of its peers.
Can I add --legacy-peer-deps to package.json permanently?+
Yes — add it to .npmrc instead: legacy-peer-deps=true. Commit this file to git and every developer plus every CI/CD pipeline will use it automatically.

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