Why npm install Fails After Upgrading: Peer Dependency Conflicts Explained

Getting ERESOLVE errors after upgrading? Learn what peer dependency conflicts are, why they happen, and how to fix them without --force.

The Dreaded ERESOLVE Error

You just upgraded a package and now npm install fails with:

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from react-beautiful-dnd@13.1.1

This is a peer dependency conflict — one of the most common and frustrating issues in JavaScript projects. Let's break down what's happening and how to fix it properly.

What Are Peer Dependencies?

Peer dependencies are packages that a library expects YOU to install. Unlike regular dependencies (which the library bundles itself), peer deps say: "I need this to exist in your project, but you choose the version."

For example, react-dom has a peer dependency on react. It doesn't bundle React — it expects your project to have React installed.

Why Conflicts Happen

Conflicts occur when two packages require incompatible versions of the same peer dependency:

your-project
├── react@19.0.0          (you installed this)
├── react-beautiful-dnd   (needs react ^17.0.0)  ← CONFLICT!
└── react-router-dom@6    (needs react ^16.8 || ^17 || ^18 || ^19)  ← OK

How NOT to Fix It

Don't use --force or --legacy-peer-deps as a long-term solution. These flags hide the problem but don't fix it. Your app may crash at runtime with cryptic errors because packages are using incompatible versions.

How to Actually Fix It

Identify the conflict: Read the ERESOLVE error carefully. It tells you which package requires which version.
Check compatibility: Use the DepFixer Compatibility Checker to verify if updated versions exist.
Update the conflicting package: Often a newer version of the library supports your framework version.
Replace deprecated packages: Some packages are abandoned. Find modern alternatives.
Scan your full project: One conflict often means there are more. Upload your package.json to find all of them at once.

Common Peer Dependency Conflicts

React 19 + older libraries — Many React libraries still specify react@^17 || ^18 without ^19.
Angular + TypeScript — Each Angular version requires a specific TypeScript range.
Angular + RxJS — Angular 16+ requires RxJS 7. Older RxJS 6 won't work.
Next.js + React — Next.js versions are tightly coupled to React versions.

Automate Conflict Detection

Instead of debugging ERESOLVE errors manually, let DepFixer scan your project:

CLI: npx depfixer — scans your local project in seconds
Web: Upload package.json — full analysis with fix recommendations