Lingua-e
← Errors
JavaScript

npm Peer Dependency Conflict: What It Means and How to Fix It

Error reference

npm Peer Dependency Conflict

Language

JavaScript

Severity

Medium

When it happens

npm throws a peer dependency conflict (ERESOLVE) when a package requires a specific version of another package that is incompatible with what is currently installed.

Potential fixes

Upgrade your version of the peer dependency if possible. Pin to an older version of the package that supports your current stack. Use --legacy-peer-deps only as a last resort and test thoroughly. Use npm ls to visualize the dependency graph.

Related errors

ModuleNotFoundErrorERR_MODULE_NOT_FOUNDERR_REQUIRE_ESM

Deep dive

npm throws a peer dependency conflict (ERESOLVE) when a package requires a specific version of another package that is incompatible with what is currently installed. npm v7+ treats unresolved peer dependencies as hard errors by default.

Why it happens

  • •A plugin or library requires a newer major version of a peer dependency than you have.
  • •Two packages in your dependency tree require conflicting versions of the same peer.
  • •Upgrading one package without upgrading its peers.
  • •A package has not been updated to support the latest major version of its peer.

Potential fixes

Upgrade your version of the peer dependency if possible. Pin to an older version of the package that supports your current stack. Use --legacy-peer-deps only as a last resort and test thoroughly. Use npm ls to visualize the dependency graph.

Examples

JavaScript

Code that triggers the error

npm install some-plugin

Error output

npm warn ERESOLVE overriding peer dependency
npm error code ERESOLVE
npm error While resolving: some-plugin@2.0.0
npm error Found: react@17.0.2
npm error node_modules/react
npm error   react@"17.0.2"
npm error
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" required by some-plugin@2.0.0

Fixed code

# Option 1: upgrade the peer dependency
npm install react@18

# Option 2: use legacy peer dep resolution (use with caution)
npm install some-plugin --legacy-peer-deps

# Option 3: use a version of the plugin compatible with your React version
npm install some-plugin@1.x

Practice in English

How would you explain a npm Peer Dependency Conflict to a fellow dev? Choose the right phrase:

"I hit an error...

Ready to practice your English at work?

Lingua-e has interactive exercises built around real developer conversations: standups, code reviews, retrospectives, and more. Practice until it comes naturally.

Try Lingua-e for free