How to Fix npm ERR! ERESOLVE unable to resolve dependency tree [2026 Latest Guide]

Have you ever encountered the error “npm ERR! ERESOLVE unable to resolve dependency tree” when running npm install in a Node.js project? This error is a common issue that many developers face daily due to the stricter dependency resolution rules introduced in npm 7 and later. In this article, we will explain in detail the causes of this error, specific solutions, and preventive measures based on the latest information in 2026.

What Is This Error? Symptoms When It Occurs
Causes of This Error
Solution 1: Use the –legacy-peer-deps Flag (Recommended)
Solution 2: Perform a Clean Install
Solution 3: Manually Adjust Package Versions (Advanced)
How to Prevent This Error
Summary
References

What Is This Error? Symptoms When It Occurs

“npm ERR! ERESOLVE unable to resolve dependency tree” is an error that occurs when npm detects incompatible package version combinations while building the project’s dependency tree. Specifically, you will see an error message like this:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: your-project@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.0.0
npm ERR! node_modules/some-package
npm ERR!   some-package@"^2.0.0" from the root project

When this error occurs, the npm install command is interrupted, and the required packages are not installed. As a result, the project cannot be built or run. This error commonly occurs in the following situations:

When cloning an existing project and installing dependencies
When trying to add a new package
After upgrading Node.js or npm versions
During automatic builds in CI/CD pipelines

Issues that were displayed as warnings before npm 6 are now treated as errors from npm 7 onwards, significantly increasing the frequency of encountering this error.

Causes of This Error

Cause 1: Peer Dependency Conflicts

The most common cause is peer dependency conflicts. A peer dependency is a mechanism where a package declares “if you use this package, you need a specific version of another package.”

For example, if a React-based UI library requires React 17, but your project uses React 18, a peer dependency conflict occurs. When multiple packages require different versions of React, npm cannot build the dependency tree.

This problem frequently occurs during major version upgrades for frameworks like React, Angular, and Vue. Since it takes time for third-party libraries to support new versions, version mismatches often occur between the project and dependent packages.

Cause 2: Strict Dependency Resolution in npm 7 and Later

The changes introduced in npm 7 fundamentally changed how peer dependencies are handled. Before npm 7, peer dependency conflicts were only displayed as warnings, and installation continued. However, from npm 7 onwards, peer dependency conflicts are treated as errors, and installation is interrupted.

This change was introduced to detect dependency issues early, but it has caused compatibility issues with many existing projects and older packages. This error frequently occurs, especially in projects using packages that have not been maintained for a long time.

Cause 3: Inconsistency Between package-lock.json and package.json

When the package-lock.json file is out of sync with package.json, this can also cause the error. This occurs in situations such as:

Using a lock file generated by a different npm version
Not updating the lock file after manually editing package.json
Multiple developers working in different environments
Lock file corruption during git merges

Cause 4: Cache Issues

If old or corrupted data remains in npm’s cache, dependency resolution may fail. This is particularly likely to occur when frequently switching package versions or when downloads are interrupted due to network issues.

Cause 5: Node.js Version Compatibility Issues

This error can also occur when the Node.js version you’re using doesn’t match the version required by the packages you’re trying to install. Some packages only work with specific Node.js versions, making Node.js version management important.

Solution 1: Use the –legacy-peer-deps Flag (Recommended)

The easiest and safest solution is to use the --legacy-peer-deps flag. By adding this flag, you can use the npm 6 era dependency resolution algorithm, ignoring peer dependency conflicts and continuing with installation.

Step 1: Basic Usage

Run the following command in your terminal:

npm install --legacy-peer-deps

When installing a specific package:

npm install package-name --legacy-peer-deps

For example, when installing React-related libraries:

npm install react-router-dom --legacy-peer-deps

Step 2: Make It the Default Setting via .npmrc File

If adding the flag every time is tedious, you can create a .npmrc file in the project’s root directory to enable --legacy-peer-deps by default:

# Run in project root
echo "legacy-peer-deps=true" > .npmrc

Or, to apply it as a global setting:

npm config set legacy-peer-deps true

This will automatically apply --legacy-peer-deps to future npm install commands.

Step 3: Utilize package.json resolutions (Optional)

When using Yarn or when more fine-grained control is needed, you can add a resolutions field to package.json to force specific package versions:

{
  "resolutions": {
    "react": "18.2.0"
  }
}

Important Notes

--legacy-peer-deps is a safe option, but it means ignoring peer dependency warnings. This implies that compatibility issues between packages might be overlooked. Make sure to test that your application works correctly before deploying to production.

Also, this flag only relaxes peer dependency checks while maintaining other security checks. Therefore, it’s a safer choice than the --force flag.

Solution 2: Perform a Clean Install

When the dependency tree is complex and tangled, a clean install is effective. This allows you to clear out existing problematic dependencies and rebuild from a fresh state.

Step 1: Remove Existing Dependencies

First, delete the node_modules directory and package-lock.json:

For Windows:

rmdir /s /q node_modules
del package-lock.json

For macOS/Linux:

rm -rf node_modules
rm package-lock.json

Step 2: Clear npm Cache

Clear the cache as old cache might be causing the problem:

npm cache clean --force

Step 3: Reinstall Dependencies

Reinstall dependencies from a clean state:

npm install

If the error still occurs, combine with --legacy-peer-deps:

npm install --legacy-peer-deps

One-liner Command

To execute the above steps together:

For macOS/Linux:

rm -rf node_modules package-lock.json && npm cache clean --force && npm install --legacy-peer-deps

For Windows (PowerShell):

Remove-Item -Recurse -Force node_modules; Remove-Item package-lock.json; npm cache clean --force; npm install --legacy-peer-deps

This method is particularly effective when taking over a project from another developer or resuming a project that has been abandoned for a long time.

Solution 3: Manually Adjust Package Versions (Advanced)

If you want a fundamental solution, you can manually adjust package versions. This allows you to build long-term stable dependencies.

Step 1: Analyze the Error Message in Detail

The error message indicates which package requires which version:

npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-library@2.0.0

In this example, some-library@2.0.0 requires React 17.

Step 2: Identify Compatible Versions

Search for the package on the npmjs website and check compatible versions. Often, the latest version of a package supports newer React versions:

npm view some-library versions
npm view some-library peerDependencies

Step 3: Update package.json

Once you find a compatible version, update package.json:

{
  "dependencies": {
    "some-library": "^3.0.0"
  }
}

Or, when downgrading to match a specific React version:

{
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}

Step 4: Use npm-check-updates (Optional)

When updating multiple packages at once, the npm-check-updates tool is convenient:

npx npm-check-updates -u
npm install

Using the overrides Field (npm 8.3+)

From npm 8.3 onwards, you can add an overrides field to package.json to override specific dependency versions:

{
  "overrides": {
    "some-library": {
      "react": "^18.0.0"
    }
  }
}

This allows you to forcibly override the React version required by some-library to 18. However, this method may cause unexpected behavior, so test thoroughly.

How to Prevent This Error

Regular Dependency Updates

By regularly updating your project’s dependencies, you can minimize peer dependency conflicts. Check for outdated packages weekly with the npm outdated command:

npm outdated

Node.js and npm Version Management

Use version management tools like nvm to use the appropriate Node.js version for each project:

# Create .nvmrc file
echo "18.17.0" > .nvmrc

# Run in project directory
nvm use

Measures for CI Pipelines

To avoid this error in CI/CD pipelines, include the .npmrc file in your repository or add flags to the install command:

# GitHub Actions example
- name: Install dependencies
  run: npm ci --legacy-peer-deps

Unifying Rules Within the Team

When developing as a team, it’s important to unify the following rules:

Node.js and npm versions to use
Rules for committing package-lock.json
Verification process when adding new packages

Summary

The “npm ERR! ERESOLVE unable to resolve dependency tree” error is a common issue caused by stricter dependency checks from npm 7 onwards. To address this error, this article introduced three approaches:

–legacy-peer-deps flag: The easiest and safest method. This resolves most cases
Clean install: Effective when dependencies are complex and tangled
Package version adjustment: An advanced method for achieving a fundamental solution

First, try npm install --legacy-peer-deps, and if that doesn’t work, try a clean install. In the long term, it’s important to regularly update dependencies and maintain project health.

If this error cannot be resolved or if problems occur with specific packages, check issues on that package’s GitHub repository or search for similar problems on Stack Overflow.