Fix npm ERESOLVE Peer Dependency Conflicts: Root Cause and Minimal Fixes

Quick Answer

• Conclusion: npm ERESOLVE errors occur when installed packages request peer dependencies that conflict with versions already in the dependency tree. The fix is to diagnose the conflict chain with npm explain, then either upgrade the parent package or add an overrides block in package.json.
• First checks: Run npm install 2>&1 | head -80 to see the full error, then npm explain <conflicting-package> to trace the conflict chain. Check if the parent package has a newer version that supports your current dependency versions.
• Minimal fix: If upgrading the parent package is possible, run npm install <parent>@latest. Otherwise, add an overrides block to package.json, delete node_modules and package-lock.json, then reinstall.
• Version boundary: npm overrides requires npm >= 8.3.0. Older versions silently ignore the field. For npm 7.x, use --legacy-peer-deps as a temporary workaround only.

When This Error Appears

The ERESOLVE error typically surfaces in these scenarios:

• Framework upgrades: Upgrading React, Vue, or Angular to a new major version while some dependencies still require the old version as a peer dependency.
• Monorepo projects: Multiple sub-packages depend on different versions of the same library, causing hoisting conflicts.
• CI/CD pipelines: npm ci fails because the lockfile is out of sync with package.json after dependency changes.
• Team collaboration: Different developers use different package manager versions, leading to inconsistent dependency trees.

Root Cause Analysis

npm 7+ introduced strict peer dependency resolution by default. When npm encounters a package that declares a peer dependency on version X, but another package in the tree already installed version Y (where X and Y are incompatible), npm throws an ERESOLVE error instead of silently proceeding.

The conflict chain typically looks like:

package-a@1.0.0
└── peer dependency: react@"^17.0.0"
package-b@2.0.0
└── dependency: react@"^18.0.0" (already installed)

npm cannot satisfy both constraints simultaneously, so it fails.

Diagnostic Commands

Before applying any fix, diagnose the exact conflict:

BASH
# See the full error message
npm install 2>&1 | head -80

# Trace the conflict chain for a specific package
npm explain <conflicting-package>

# List the entire dependency tree
npm ls --all --depth=5

# Check what versions are available for the parent package
npm view <parent-package> versions --json

For yarn users, the equivalent commands are:

BASH
yarn why <package>
yarn info <package> versions

For pnpm users:

BASH
pnpm why <package>
pnpm ls --depth=5

Minimal Working Configuration

Fix 1: Upgrade the Parent Package (Preferred)

BASH
# Check available versions
npm view <parent-package> versions --json

# Upgrade to the latest version
npm install <parent-package>@latest

# If that doesn't work, try a specific version
npm install <parent-package>@<specific-version>

Fix 2: Use overrides (npm >= 8.3.0)

Add to package.json:

JSON
{
  "overrides": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

For more specific overrides targeting a particular dependency chain:

JSON
{
  "overrides": {
    "some-package": {
      "react": "^18.0.0"
    }
  }
}

Then clean and reinstall:

BASH
rm -rf node_modules package-lock.json
npm install

Fix 3: Temporary Workaround (Not for Production)

BASH
# npm 7.x only - skip peer dependency checks
npm install --legacy-peer-deps

# npm 8+ - force installation
npm install --force

Warning: These flags hide real compatibility issues and can cause runtime errors. Never use them in CI/CD or production environments.

Common Errors and Fixes

Production Notes and Security Checks

Critical Limitations

1. Root-only overrides: npm and yarn overrides/resolutions only work in the root package.json. Workspace sub-package overrides are ignored.
2. Clean reinstall required: After modifying overrides, you must delete node_modules and lockfiles, then reinstall. Otherwise, the overrides may not take effect.
3. No legacy flags in production: --legacy-peer-deps and --force hide real compatibility issues and should never be used in CI/CD or production.
4. pnpm behavior: pnpm does not auto-install conflicting peer dependencies. It prints warnings and skips them, requiring manual handling via pnpm.peerDependencyRules.
5. npm version requirement: overrides requires npm >= 8.3.0. Older versions silently ignore the field.

Security Recommendations

• Run npm audit regularly to check dependency security.
• Use npm ci in CI pipelines instead of npm install for deterministic builds.
• When overriding third-party packages, ensure the replacement version has been security-reviewed.
• Avoid setting legacy-peer-deps=true in global .npmrc files.

Comparison With Alternatives

The key advantage of this diagnostic-first approach is that it works across all major package managers, emphasizing root cause resolution over force-installing problematic dependencies.

FAQ

Q: Why does --legacy-peer-deps succeed but cause runtime errors?

A: --legacy-peer-deps skips peer dependency version checks, allowing incompatible dependency combinations to install. This can cause runtime type errors, missing API calls, or broken functionality. For example, if a React component library requires react@17 but your project uses react@18, components using deprecated APIs may fail. The correct approach is to diagnose the conflict with npm explain and resolve it explicitly through upgrades or overrides.

Q: Why don't overrides in workspace sub-packages work?

A: npm and yarn overrides/resolutions only take effect in the root package.json. For workspace sub-packages, hoisted dependencies are lifted to the root node_modules, so sub-package overrides are ignored. Always place all overrides in the root package.json. After modifying them, perform a full clean reinstall from the workspace root (delete all node_modules and lockfiles) to ensure the overrides take effect.

Q: How does pnpm handle peer dependency conflicts differently from npm and yarn?

A: pnpm does not auto-install conflicting peer dependencies. When it detects a conflict, it prints a warning and skips the installation, rather than throwing an ERESOLVE error like npm. Developers must handle conflicts manually. pnpm provides pnpm.peerDependencyRules for granular control: ignoreMissing to skip missing peer deps, allowedVersions to specify allowed version ranges, and allowAny to permit any version. pnpm also supports the overrides field for forcing dependency versions. This design makes pnpm's dependency tree stricter and more predictable.