Diagnosing and Resolving npm ERESOLVE Dependency Tree Conflicts

The ERESOLVE Conflict

When running npm install in npm v7 or later, you may encounter the npm ERR! ERESOLVE unable to resolve dependency tree error. This occurs because npm v7+ automatically installs peer dependencies by default. A peer dependency is a package that a library requires to function, but expects the consuming application (your project) to provide.

The error triggers when two or more packages in your dependency tree require incompatible versions of the same peer dependency. Rather than silently installing a version that might break one of the packages, npm halts the process. The takeaway: this is a safety check to prevent runtime crashes caused by incompatible library versions.

Diagnostic Matrix

Review the CLI output provided during the error to identify the specific conflict type.

CLI Indicator	Root Cause	Risk Level
"Conflicting peer dependency"	Two packages require different, non-overlapping version ranges of the same library.	Medium
"Peer dependency unmet"	A package requires a peer dependency that is not present in the tree.	Low
"Invalid version range"	The requested version is incompatible with the current Node.js environment or constraints.	High

Resolution Path

Follow these checks in order. Only proceed to the next step if the previous one does not resolve the conflict or is not applicable to your project constraints.

1. Analyze the Dependency Chain

The ERESOLVE output contains a trace showing exactly which packages are fighting. Look for the section starting with Conflicting peer dependency.

# Example trace logic
# Package-A@1.0.0 requires react@^16.0.0
# Package-B@2.0.0 requires react@^17.0.0
# Result: ERESOLVE conflict on 'react'

2. Update the Conflicting Package

The most stable fix is to update the package that is requesting the outdated peer dependency. Check the package's documentation or registry for a newer version that supports your current environment.

# Run in project root as a user with write permissions to package.json
npm install package-name@latest

3. Use --legacy-peer-deps

If you cannot update the package (e.g., the library is no longer maintained) and you believe the version mismatch will not cause a crash, use the legacy flag. This tells npm to ignore peer dependencies entirely, reverting to the installation behavior of npm v6.

# Run in project root
npm install --legacy-peer-deps

Risk: This may lead to runtime TypeError or undefined errors if the package attempts to call a function that does not exist in the version of the peer dependency actually installed.

4. Use --force

The --force flag forces npm to fetch the packages and potentially overwrite existing versions in the node_modules tree to satisfy the most recent request.

# Run in project root
npm install --force

Risk: This can create a non-deterministic node_modules state. Your local environment may differ from your CI/CD pipeline, leading to bugs that are difficult to reproduce across different machines.

Verification and Validation

After the installation completes, verify that the resulting tree is functional.

1. Check Resolved Version: Run npm list <package-name> to see which version was actually resolved and where it sits in the tree.
2. Verify Runtime: Execute your test suite (e.g., npm test). Focus on modules that rely on the conflicting dependency.
3. Lockfile Audit: Ensure package-lock.json was updated and commit it to maintain consistency across the team.

Rollback Procedure

If the installation succeeds but the application crashes or behaves unexpectedly, revert the state by clearing the local environment:

# Run in project root
rm -rf node_modules package-lock.json
npm install

Escalation Criteria

If the standard flags do not resolve the issue or cause too many runtime errors, use these advanced methods:

• Dependency Overrides: For npm v8.3+, add an "overrides" section to package.json. This forces a specific version of a dependency across the entire tree, regardless of what individual packages request.
• Forking: If a critical library is abandoned, fork the repository, update the peerDependencies range in its package.json, and install from your fork.