[Resolved] NPM error - Fix the upstream dependency conflict

Introduction

I was working on a recent React app and when I ran the command: npm install I am getting the following error of:

npm ERR! Fix the upstream dependency conflict, or retry

Ok? What the heck does this mean? A more verbose error looks like the following output:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: practice1@0.1.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@"~0.14.9 || ^15.0.0 || ^16.0.0" from react-image-magnify@2.7.4
npm ERR! node_modules/react-image-magnify
npm ERR! react-image-magnify@"*" 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.

So what does this all mean anyway? From the verbose error above, we can see that the main line is:

npm ERR! peer react@"~0.14.9 || ^15.0.0 || ^16.0.0" from react-image-magnify@2.7.4

So when we run npm install, during installation of the package react-image-magnify@2.7. requires react versions ~0.14.9, ^15.0.0, and ^16.0.0

Now my app only contains react version 18.2.0 - thats why it is spitting out this upstream dependency error

What is a upstream dependency anyway?

Upstream dependencies are really just indirect dependencies that NPM installs.

So for example, in your project, we install a NPM package called “react-image-magnify”. Now when NPM installs this package it also sees that this package has a dependency on React and it will also install it!

The problem arises when you have also have React installed - NPM does not know which version to take!

To fix this error, there are a few simple things we can try:

1. Use npm install --save --legacy-peer-deps
2. Inspect the logs and upgrade NPM packages accordingly
3. Use the Yarn package manager
4. Downgrade your version of NPM
5. Clear the cache with npm cache clean --force and npm i --force
6. Remove the node_modules folder and then package-lock.json. Then install all packages again.

1. Use npm install --save --legacy-peer-deps

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

npm install --save --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.

2. Inspect the logs and upgrade NPM packages accordingly

The cleanest way to fix this error is to go through the error log and see what NPM packages we need to update.

Consider the following example error log where we are trying to install the react-image-magnify NPM package:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: practice1@0.1.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@"~0.14.9 || ^15.0.0 || ^16.0.0" from react-image-magnify@2.7.4
npm ERR! node_modules/react-image-magnify
npm ERR! react-image-magnify@"*" 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.

Now looking at the error log, we can see that react-image-magnify has peer dependencies for React - react@"~0.14.9 || ^15.0.0 || ^16.0.0".

The problem is that our current project, we have installed React already but version 18

To get around this, we have the following options:

• Revert to the React versions thats compatible with react-image-magnify
• Upgrade react-image-magnify so that it has peer dependencies thats meets our project’s React version
• Use another image package

3. Use the Yarn package manager:

Yarn is an alternative package manager which can help resolve peer dependencies conflicts more quickly than NPM.

Consider the following Angular error with peer dependencies:

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.

One tip is to use the Yarn package manager instead of NPM. Yarn is pretty a wrapper around NPM, but it contains features thats more of an improvement.

Steps to use Yarn and fix this peer dependency error are as follows:

1. Delete the node_modules folder in your project.
2. Delete the package-lock.json files. You may need to back up your project first. Note: Do not delete 1package.json1. We will need this to install our packages!
3. Run the command to install yarn: npm i yarn. (We can install globally with the -g flag)
4. Go to the root directory of your project and run the command yarn install.

If you are already using yarn, we can use the following command:

yarn add @angular/common@10.0.0

Hopefully this should fix up the peer dependency issue!

4. Downgrade your version of NPM

If you are using NPM 7.x or higher, this will most likely break your code than with NPM version 6.x or below. One key difference with NPM version 7.x is that it installs peer dependencies by default!

This can cause version/dependency conflicts and introduce breaking the installation process.

We see this issue most commonly with React v17+ projects (or version 18 now).

A lot of React modules did not include the peer dependency of React v17 and when you run npm install, it will give the unable to resolve dependency tree error.

Since NPM version 7.x requires peer dependencies to be explicitly specified, this error will fire whenever a module (or any of its own dependencies) lists a previous major version of React as a peerDependency without specifically including React v17 as well.

5. Clear the cache with npm cache clean --force and npm i --force

One fix is to try:

npm cache clean --force
npm i --force

Sometimes, your dependencies are correct, but you still get the conflicting peer dependency error. This could be due to NPM still looking through the cached modules.

NPM usually stores modules in your local project folder and also a “cached” folder. This will be ~/.npm on linux/ OSX systems, or %AppData%/npm-cache for windows systems.

So the next time you install a similar module it will go off to the cache instead of downloading it! The above command just clears the cache folder.

6. Remove the node_modules folder and then package-lock.json. Then install all packages again.

When previous steps did not work for you, the final option is to nuke everything.

Open up your terminal and go to the project’s root folder:

1. Delete node_modules folder. This is where all the packages are saved.
2. Delete the package-lock.json.
3. Run npm install
4. Run npm install --legacy-peer-deps if the above still giving conflict errors

Fixes for Angular projects

For Angular projects, a similar error occurred when I was upgrading from Angular 12 to Angular 13.

When I run NPM install after the upgrade, I get the following error:

CREATE my-workspace/README.md (1057 bytes)
CREATE my-workspace/.editorconfig (274 bytes)
CREATE my-workspace/.gitignore (620 bytes)
CREATE my-workspace/angular.json (139 bytes)
CREATE my-workspace/package.json (1028 bytes)
CREATE my-workspace/tsconfig.json (863 bytes)
CREATE my-workspace/.vscode/extensions.json (130 bytes)
CREATE my-workspace/.vscode/launch.json (474 bytes)
CREATE my-workspace/.vscode/tasks.json (938 bytes)
⠴ Installing packages (npm)...npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-workspace@0.0.0
npm ERR! Found: typescript@4.5.5
npm ERR! node_modules/typescript
npm ERR!   dev typescript@"~4.5.2" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer typescript@">=4.4.2 <4.5" from @angular/compiler-cli@13.0.3
npm ERR! node_modules/@angular/compiler-cli
npm ERR!   dev @angular/compiler-cli@"~13.0.0" 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/drorrash/.npm/eresolve-report.txt for a full report.

A few options we can do to solve this includes:

• Using the --legacy-peer-deps flag if you have NPM version greater than version 7.
• Downgrade to NPM version 6 with the command npm i -g npm@6

Summary

In this post, I went over the npm error “fix the upstream dependency conflict”. This error comes up when there are issues with your peer dependencies. A peer dependency is a indirect dependency from your project’s packages.

To fix this error, we can use the --legacy-peer-deps flag, find the conflicting package and downgrade or upgrade the relevant packages in our project, clear the cache or download NPM version 6.

If the previous steps did not work, then we can try the nuke option of clearing node_modules and package-lock.json and reinstalling again.