Introduction

npm enforces peer dependency rules to ensure that packages requiring specific versions of other packages get compatible versions. After updating a package, its peer dependency requirements may conflict with what is already installed, causing npm install to fail with "ERESOLVE unable to resolve dependency tree".

This is especially common in React, Angular, and Vue projects where plugins require specific framework versions.

Symptoms

  • npm install fails with "ERESOLVE could not resolve"
  • Error shows "peer react@'^18.0.0' from react-dom@18.2.0" conflicting with installed react@17.0.2
  • npm install worked before but fails after updating one package

Common Causes

  • Updated package requires a newer (or older) version of a peer dependency
  • Two packages require incompatible versions of the same peer dependency
  • Major version upgrade of a framework breaks plugin compatibility

Step-by-Step Fix

  1. 1.Identify the conflicting peer dependencies: Use npm ls to see the dependency tree.
  2. 2.```bash
  3. 3.# Show the full dependency tree with conflicts:
  4. 4.npm ls react

# Show why a specific package cannot be installed: npm explain react

# Output shows the conflict: # react@17.0.2 # node_modules/react # react@"^17.0.2" from the root project # peer react@"^17.0.0 || ^18.0.0" from some-lib@2.1.0 # BUT peer react@"^18.0.0" from other-lib@3.0.0 ```

  1. 1.Update the peer dependency to a compatible version: Align versions across packages.
  2. 2.```bash
  3. 3.# Update React to satisfy both peer requirements:
  4. 4.npm install react@^18.0.0 react-dom@^18.0.0

# Then reinstall the conflicting package: npm install some-lib@latest

# Verify no conflicts remain: npm ls ```

  1. 1.Use --legacy-peer-deps as temporary workaround: Skip peer dependency checks.
  2. 2.```bash
  3. 3.# Bypass peer dependency resolution:
  4. 4.npm install --legacy-peer-deps

# Or set it as default (not recommended for new projects): npm config set legacy-peer-deps true

# WARNING: This may cause runtime errors if the packages are truly incompatible ```

Prevention

  • Check peer dependency requirements before updating major packages
  • Use npm outdated regularly to plan coordinated upgrades
  • Pin dependency versions in package.json to avoid surprise conflicts
  • Use npm ls in CI to verify dependency tree health after every install