Fixed - NPM ERR ERESOLVE unable to resolve dependency tree

Introduction

A frustrating issue when working with large Node or Javascript projects is dealing with package conflicts or also known as dependency hell!

Recently I was firing up a medium-ish React project and got the error:

NPM ERR ERESOLVE unable to resolve dependency tree

Now if I look at the error logs, it has a bit more information:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: soft-ui-dashboard-pro-react@3.1.0
npm ERR! Found: react@17.0.2
npm ERR! node_modules/react
npm ERR!   react@"17.0.2" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^0.14.9 || ^15.3.0 || ^16.0.0" from react-quill@1.3.5
npm ERR! node_modules/react-quill
npm ERR!   react-quill@"1.3.5" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! See /Users/amin/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/amin/.npm/_logs/2022-03-23T05_47_43_419Z-debug-0.log

So the important line in the error log is: npm ERR! peer react@"^0.14.9 || ^15.3.0 || ^16.0.0" from react-quill@1.3.5

NPM is complaining that it could not resolve the peer dependency that is required from react-quill. This package react-quill (version 1.3.5) requires peer dependencies of react versions "^0.14.9", “^15.3.0”, “^16.0.0”.

However this causes peer dependency problems since our project contains react@“17.0.2”.

To fix this we can:

• Downgrade to the React versions that suits react-quill
• Use the --legacy-peer-deps flag
• Upgrade react-quill to a version that supports the latest React (or the version that your project is using. In our case React version 17.0.2)

What are peer dependencies?

Peer dependencies in npm are a way to declare that a package has a dependency on another package, but it doesn’t manage the installation of that dependency.

Instead, it expects the user or consuming project to manage and install the correct version of the dependent package.

This is often used in plugins or libraries that extend the functionality of another package.

Steps to fix this error

This error can come up due to different type of reasons. To fix this, we can go through this checklist of ways to troubleshoot it:

1. Figure out and resolve the conflicting dependency
2. Clear cache, remove node_modules, package-lock.json and reinstall everything
3. Upgrade to the latest NPM version or use a specific version
4. Use the --legacy-peer-deps flag
5. Use yarn instead of NPM as your package manager
6. Downgrade your version of NPM

1. Figure out and resolve the conflicting dependency

The first thing to do when this error of unable to resolve dependency tree is to check what is spitting out of the log and try to figure out the right package to install.

Lets consider this Angular project that was troubling me a few months ago:

npm ERR! ERESOLVE unable to resolve dependency tree

npm ERR! while resolving: gf-kautomata-pipeline-uige.e.e

npm ERR! Found: @angular/core@9.1.12

npm ERR! node_modules/@angular/ core
npm ERR! @angular/core@"^9.1.4" from the root project

npm ERR! Could not resolve dependency:
npm ERR! peer @angular/core@7.2.16" from @angular/http@7.2.16
npm ERR! node_modules/@angular/http

npm ERR! @angular/http@"7.2.11" from the root project

npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

...
...
npm ERR! code ETARGET
npm ERR! notarget No matching version found for @angular/http@"^9.1.4".

npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.

npm ERR! A complete log of this run can be found in

Now if we look closely at the error logs, we can see the lines:

npm ERR! notarget No matching version found for @angular/http@"^9.1.4".

We can see that NPM is trying to find the package @angular/http, but if we look at the Angular version page (https://www.npmjs.com/package/@angular/http?activeTab=versions), there is no version 9.x.x.

As of writing (2023) the max version is 8.

2. Clear cache, remove node_modules, package-lock.json and reinstall everything

One option that worked well for NPM issues for me is to nuke the whole project - removing node_modules and reinstall everything.

To do this we can use the steps, open up the terminal and make sure you are in the root directory of the project:

1. rm -rf node_modules to remove the existing modules.
2. rm -rf package-lock.json - removing the package-lock.json file.
3. Run npm cache clean --force to make sure we don’t have random modules from the cache.
4. Execute npm install to re-install the project dependencies.

3. Upgrade to the latest NPM version or use a specific version

To make sure that this issue is not caused by some bug in your installed version of NPM, it is recommended to install the latest version.

To troubleshoot this error, we need to make sure that we are on the latest version of NPM.

First, we need to find the current version installed. Open a terminal or command prompt and run the following command:

npm --version

or this command will also work:

npm -v

Now if the version is not the latest, we can update it as follows:

npm install -g npm@latest

4. Use the --legacy-peer-deps flag

We can use the --legacy-peer-deps flag to ignore this error:

npm install --legacy-peer-deps

Starting from NPM version 7 and onwards, they worked the algorithm to manage peer or upstream dependencies. This new algorithm installs peer dependencies as a default!

Older versions of NPM (eg 6) are more relaxed on how they handle peer dependencies so thats why you don’t see this error.

Essentially, NPM 7+ treats peer dependencies as follows:

• install peer dependencies by default. This is not required in previous versions.
• modules MUST have peer dependencies specified or it will throw an error

The flag --legacy-peer-deps applies for NPM 7+ and tells NPM to use the algorithm that handles peer dependencies from NPM version 6 and below.

5. Use yarn instead of NPM as your package manager

If you still have problems with dependencies, instead of using NPM, consider switching over to Yarn to manage packages.

Yarn is generally known to be better than NPM in:

• Dependency management,
• Performance and speed
• Reliability with flaky internet connections

(Although NPM is improving as well, so these differences might be negligible in the future)

Lets say we have a Angular project, and ran npm install and got the following error:

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: project-admin@11.0.0
npm ERR! Found: @angular/common@11.0.3
npm ERR! node_modules/@angular/common
npm ERR!   @angular/common@"11.0.3" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/common@"^9.1.0 || ^10.0.0" from @agm/core@3.0.0-beta.0
npm ERR! node_modules/@agm/core
npm ERR!   @agm/core@"3.0.0-beta.0" from the root project

In the above error @agm/core@3.0.0-beta.0 requires @angular/common version ^9.1.0 or ^10.0.0.

And the actual @angular/common version 11.0.3.

Now in this case, using NPM will give you the error: unable to resolve dependency tree, but Yarn can better manage the dependency tree.

To install and use Yarn as your package manager, follow these steps:

1. First, ensure that you have Node.js installed on your system. You can download it from the official website: https://nodejs.org/

2. Install Yarn globally using npm (Node.js’s default package manager):

npm install -g yarn

3. Verify that Yarn has been installed correctly by checking its version:

yarn --version

4. Now that Yarn is installed, go to your project directory and install all packages in the package.json file as follows:

cd my-project
yarn install

6. Downgrade your version of NPM

Now if all the other options did not work, we can try to go back to NPM version 6.

Why version 6? This is because from NPM version 7 and onwards, it will install peer dependencies by default!

Instead of downgrading NPM for just one project, we can use npx and specify the NPM version when we do npm install:

npx -p npm@6 npm install

I often see this issue with React projects. There are a lot of React projects that do not include a peer dependency for React, so when combined with NPM 7 (where peer dependency is mandatory), you will get the error:

unable to resolve dependency tree

Summary

In this post, we went over a common error with Node and Javascript packages unable to resolve dependency tree. This can get frustrating since instead of working on your project, you are dealing with dependency hell.

The error is usually caused by incompatible peer dependencies for one of the packages that your project relies on.

To fix these types of errors, we can go through the checklist of:

• Upgrading or downgrading the package to make sure you have the compatible version in your project
• Use the --legacy-peer-deps flag when running NPM install
• Consider using Yarn to manage your packages
• All out nuke approach and clear cache, remove node_modules and package-lock.json and reinstall again!