How do I read npm "conflicting peer dependency" error messages?

Question

I'm in the process of trying to upgrade some npm dependencies of a project I own, and I'm getting a "conflicting peer dependency" error.

I see a lot of questions on this site asking for help fixing such errors. However, I've struggled to find information on what these errors actually mean. I feel like if I understood that, I'd have a fighting chance of figuring out how to solve the problem on my own.

Here's the error message I'm trying to interpret:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! Found: @angular-devkit/[email protected]
npm ERR! node_modules/@angular-devkit/build-angular
npm ERR!   dev @angular-devkit/build-angular@"~0.1102.9" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! dev @angular-devkit/build-angular@"~0.1102.9" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: @angular/[email protected]
npm ERR! node_modules/@angular/localize
npm ERR!   peerOptional @angular/localize@"^11.0.0 || ^11.2.0-next" from @angular-devkit/[email protected]
npm ERR!   node_modules/@angular-devkit/build-angular
npm ERR!     dev @angular-devkit/build-angular@"~0.1102.9" 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.

This can be reproduced by running npm install in the root of this Github branch (I'm using npm 7.10.0.)

My general understanding of a "conflicting peer dependency" error is that some package I depend upon is expressing a peer dependency on a package version spec which does not match the version of that package that I actually have installed.

For example, if my project has direct dependencies on packages A and B, and I have version 12.0.0 of A installed but my version of B has a peer dependency on ^11.0.0 of package A, then I will get a conflicting peer dependency error, because I'm using B with a version of A that it is potentially incompatible with.

Therefore, my best guess as to what this error message could mean is that some package I depend upon has a peer dependency on @angular/localize version spec ^11.0.0 || ^11.2.0-next, but this spec does not match the version of @angular/localize I have installed.

When I look at my package-lock.json, I do see that the node_modules/@angular-devkit/build-angular entry has an entry "@angular/localize": "^11.0.0 || ^11.2.0-next" in its peerDependencies.

However, this is the only mention of @angular/localize anywhere in this file -- or indeed in package.json. I haven't explicitly requested for it to be installed. Furthermore, it is marked as "optional": true in the peerDependenciesMeta of node_modules/@angular-devkit/build-angular. So it's surprising to see an error message related to it.

The error mentions that the specific conflicting peer dependency is @angular/[email protected]. I don't see where that version number is coming from. But regardless, it actually seems to match the dependency specification underneath: if I go to semver.npmjs.com and type in @angular/localize as the package and ^11.0.0 || ^11.2.0-next as the version range, I see version 11.2.10 of the package highlighted in green, indicating that it matches the range.

So I'd really appreciate some help understanding in detail what this error message is telling me. I don't know why npm is trying to install 11.2.10 of @angular/localize, or why it thinks this conflicts with the peer dependency specification of @angular-devkit/build-angular. It feels like I might be misunderstanding this message completely.

I'm guessing this boils down to some kind of incompatibility between the latest published versions of some of the Angular packages. If anyone has any pointers on how this particular error should be fixed, that would be great -- but I'm much more interested in simply understanding what the error message is telling me, so I can work it out for myself.

Many thanks in advance!

Answer 1

Reading through this GitHub issue, it appears my interpretation of the error message was correct, and that this is in fact a bug in npm.

This appears to have been reported as npm/cli/issues/3083; a fix has been merged, so I guess we just have to wait until it gets included in some upcoming npm release.

Answer 2

Recommendation:

Check out Yarn.

I was able to circumvent the issue in NPM by using Yarn instead of NPM. Yarn is basically a wrapper utility around NPM that adds extra features, which are super useful. It's especially helpful for managing NPM dependencies better.

For instance, it can check if a package is already installed on your machine for another project, directly or as a sub dependency, and can reuse that installed version rather than re-installing a copy of the same package; saves space and makes for faster installations, especially with some of the most common dependencies.

So, due to the optimized way Yarn handles dependencies, I think it helps avoid this issue faced by the OP.

Resolution:

1. First, delete the node_modules folder in your project.
2. Yarn will complain about any package-lock.json files, so delete that too (or back it up, then delete it). Do not delete package.json, yarn will need that.
3. Simply install yarn: npm i yarn (you could do this globally, too).
4. Then run yarn install in your project directory.