How to Fix npm ERESOLVE Dependency Errors

How to Fix npm ERESOLVE Dependency Errors (Step-by-Step Guide)

You run npm install expecting your project's dependencies to install normally.

Instead, npm stops with:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

This error usually means npm cannot find a compatible dependency arrangement that satisfies the packages you're trying to install.

It commonly appears after upgrading React, Next.js, ESLint, or another package that shares dependencies with plugins.

The solution isn't always to delete node_modules or force npm to continue. First, you need to identify which packages disagree about version compatibility.

In this guide, we'll explain npm's ERESOLVE error, reproduce a typical dependency conflict, and walk through safer fixes.

1. What Does npm ERESOLVE Mean?

Modern npm versions resolve dependencies by considering each package's declared requirements.

Packages can declare several dependency types:

• dependencies: Packages required by the application or library.
• devDependencies: Packages generally used for development and build tooling.
• peerDependencies: Compatibility requirements involving packages supplied by the consuming application or surrounding environment.

Peer dependencies are especially common for React libraries, ESLint plugins, and framework integrations.

For example, imagine a project using React 19 while a component library declares that it supports only React 18.

If npm cannot satisfy those requirements, installation may fail with ERESOLVE.

The error helps prevent an incompatible package combination from being installed silently.

2. Read the Error Before Changing Anything

Consider this illustrative output:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

npm ERR! While resolving: example-app@1.0.0

npm ERR! Found: react@19.0.0

npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from example-widget@1.0.0

This is a constructed example, not output captured from a published package.

It tells us:

Installed or requested package: react@19.0.0

Conflicting requirement: example-widget expects React 18.

The problem is not necessarily npm itself.

The two packages declare incompatible requirements.

Your next step is to find a compatible version of the widget, change the React version when appropriate, or replace the incompatible package.

3. Check Your Node.js and npm Versions

First, open a terminal in your project folder.

Run:

node --version
npm --version

Then inspect your project's dependency declarations:

npm pkg get dependencies
npm pkg get devDependencies

These commands help identify which versions your project requests.

Don't automatically upgrade every package. A newer major version can introduce additional breaking changes.

When following troubleshooting instructions, use the documentation for your installed npm version.

4. Find the Conflicting Dependency

npm provides commands to investigate dependency relationships.

For example:

npm ls react

This displays the installed dependency tree involving React and may show invalid dependency relationships.

If the tree cannot be installed at all, npm may not have a complete installed structure to inspect.

You can also try:

npm explain react

This helps explain why a package appears in an installed dependency tree.

To inspect the declared peer requirements of a published package, use:

npm view PACKAGE_NAME@VERSION peerDependencies

Replace the placeholders with the actual package name and version.

For example, if a package requires React 18, check whether a newer package release declares compatibility with your React version.

Important: Do not assume that a newer package version is compatible until you've checked its metadata and release notes.

5. Fix #1: Install Compatible Package Versions

The best long-term solution is usually to choose versions that are intended to work together.

Suppose your project uses a newer React major version but a plugin supports only an older version.

Possible solutions include:

1. Upgrade the plugin to a release that supports your React version.
2. Use a supported React version that meets the plugin's requirements.
3. Replace the plugin with a maintained alternative.
4. Wait for a compatible release if the feature isn't urgently needed.

For example, to install a specific compatible package release:

npm install PACKAGE_NAME@VERSION

Don't paste the placeholders unchanged.

After modifying dependencies, inspect the resulting package.json and lockfile.

Then run:

npm run build

If your project defines tests, run them too.

A successful installation is only the first check. Runtime compatibility still matters.

6. Fix #2: Review Your package.json

Sometimes a project contains version ranges that no longer make sense together.

Open package.json and inspect the related dependencies.

For example:

{
  "dependencies": {
    "react": "^19.0.0",
    "example-widget": "1.0.0"
  }
}

If example-widget only supports React 18, those requirements conflict.

This example uses a fictional package for explanation.

Don't manually change versions at random.

Find compatible releases using official package metadata, documentation, and release notes.

Once you choose supported versions, install them normally so npm updates the lockfile consistently.

7. Fix #3: Reinstall Dependencies Cleanly

Sometimes the declared dependency versions have already been corrected, but the local installation is inconsistent.

If your project has a valid, committed package-lock.json, try:

npm ci

npm ci performs a clean installation using the lockfile.

It removes the existing node_modules directory and installs the locked dependency versions.

Unlike npm install, it does not rewrite your package manifest or lockfile.

However, npm ci does not solve an incompatible dependency tree.

If your lockfile contains conflicting dependencies or requires different npm configuration, the installation may still fail.

For example, a lockfile generated using --legacy-peer-deps may require equivalent npm settings during npm ci.

Avoid deleting package-lock.json as your default response to every ERESOLVE error.

The lockfile is useful for reproducible installs.

8. Fix #4: Understand --legacy-peer-deps

You may find this command in forum discussions:

npm install --legacy-peer-deps

It can sometimes allow an installation to continue.

But why?

The --legacy-peer-deps option tells npm to ignore peer dependency requirements while building the dependency tree.

That does not make the conflicting packages compatible.

For example, a React plugin written for an older major version may install successfully but still fail when executed.

When might it be useful?

It can be a temporary diagnostic or migration workaround when you understand the compatibility risks.

It should not be the first fix for a production application.

If you use it temporarily, document why and run the relevant build, type checks, and application tests.

The preferred solution remains selecting compatible packages.

9. Why npm install --force Is Usually Not the Answer

Another commonly suggested command is:

npm install --force

The --force option removes several npm protections and can allow potentially incompatible dependency resolutions.

It is not equivalent to choosing a supported dependency tree.

You may move past the installation error only to encounter runtime failures or unexpected behavior later.

Use it only when you understand the consequences and have a specific reason.

For ordinary dependency conflicts, fix the incompatible versions instead.

10. What About package.json Overrides?

npm supports an overrides field that can influence dependency versions inside the dependency tree.

This is useful for certain transitive dependency problems.

For example, an application may need to replace a vulnerable nested package with a suitable patched version.

However, overrides are not a universal peer-dependency repair mechanism.

They can introduce their own constraints, and an override does not prove that an incompatible plugin supports your installed framework version.

Before using overrides, determine whether the problem concerns a direct dependency, a transitive dependency, or a peer requirement.

For peer compatibility problems, updating the relevant plugin or host package is often clearer.

11. Fixing ERESOLVE in Next.js Projects

A Next.js application may encounter dependency conflicts when upgrading the framework or its surrounding packages.

Possible sources include:

• React compatibility requirements.
• Third-party component libraries.
• Testing libraries.
• ESLint plugins and configurations.
• Packages that haven't been updated for newer framework versions.

Recommended workflow

Start with:

npm ls next react react-dom

Then check the relevant package requirements:

npm view next@VERSION peerDependencies

Replace VERSION with the Next.js version you intend to install.

Check that your selected React and React DOM versions satisfy the relevant constraints.

If a third-party plugin is responsible, review its compatibility requirements separately.

Don't upgrade packages blindly

Running an update command without reviewing major-version compatibility can create more problems.

Change the minimum number of packages necessary, then run your project's tests and build.

12. Why ERESOLVE Appears on Vercel but Not Locally

Sometimes installation works on your computer but fails during deployment.

Possible explanations include:

• Different npm versions.
• A missing or outdated lockfile.
• Different dependency-installation flags.
• A committed .npmrc configuration.
• Different build or install commands.

Start by comparing local and deployed environments.

Check your Node.js and npm versions, package manager, and lockfile.

Then inspect the Vercel installation logs.

If your project uses npm, aim for a consistent, committed package-lock.json.

A compatible lockfile and consistent npm configuration make deployment behavior easier to reproduce.

Related guide: Common Vercel Deployment Errors and Solutions.

13. A Safe Troubleshooting Checklist

When npm reports ERESOLVE:

1. Read the full error and identify the conflicting packages.
2. Check their declared peer dependency requirements.
3. Inspect package.json and package-lock.json.
4. Choose versions that are officially compatible.
5. Install without bypass flags where possible.
6. Run your type checks, tests, and production build.
7. Commit the updated dependency files together.
8. Verify the installation again in a clean environment.

If the error persists, use the npm debug report to inspect the full resolution details.

Avoid publishing private registry credentials or other sensitive information when sharing installation logs.

14. Common Mistakes to Avoid

Deleting the lockfile immediately. This can obscure the original dependency conflict and change many package versions at once.

Using --force as a permanent fix. Installation success doesn't guarantee runtime compatibility.

Ignoring peer dependency ranges. Plugins may depend on specific host APIs.

Updating unrelated packages. Broad upgrades make it harder to identify which change fixed or introduced the problem.

Skipping a clean-install test. A project can work on one computer and fail in CI because the dependency environment differs.

Assuming npm is broken. ERESOLVE often indicates a genuine incompatibility that needs a deliberate version decision.

Final Thoughts

The npm ERESOLVE error is frustrating, but it provides valuable information about your project's dependency compatibility.

Instead of forcing npm to ignore the conflict, identify the two packages that disagree and select versions that are designed to work together.

Start with the error message.

Check dependency declarations.

Make the smallest compatible change.

Then verify the result with a clean install, tests, and a production build.

The goal isn't simply to make npm install finish. It's to build a dependency tree your application can safely use.

Related CodeWithLogs Guides

• Common Vercel Deployment Errors and Solutions
• How to Deploy a Next.js App to Vercel
• Next.js Folder Structure for Large Projects
• package.json Inspector
• Error Decoder

Official Documentation

• npm package.json: Peer Dependencies
• npm Install
• npm Explain
• npm CI
• npm Configuration