How to Fix npm Eresolve Error: A Step-by-Step Guide

To fix the npm ERESOLVE error, run npm install --legacy-peer-deps for a temporary workaround. The lasting solution involves carefully aligning conflicting package versions in your package.json. This error indicates that npm cannot construct a dependency tree that satisfies all version requirements simultaneously.

What Does the npm ERESOLVE Error Mean?

The npm ERR! code ERESOLVE signifies a dependency conflict. Npm is unable to automatically resolve incompatible version requirements between two or more packages for a shared dependency. This means your project’s various packages are asking for different, mutually exclusive versions of another package. Npm cannot find a single version that satisfies all requests. This error became significantly more prevalent with npm version 7 and later. This version introduced a stricter dependency resolution algorithm.

Prior to npm 7, such conflicts often resulted in warnings, allowing installation but potentially leading to runtime issues. With npm v7 and newer, peer dependencies are installed by default, making a plugin’s declared peer range a strict constraint that must be met for a successful installation.

Why Dependency Conflicts Occur

Dependency conflicts typically arise when different packages in your project declare incompatible version requirements for a common dependency. This also happens with sub-dependencies of those packages. For example, if Package A requires dependency-x@^1.0.0 (meaning version 1.x.x) and Package B requires dependency-x@^2.0.0 (meaning version 2.x.x), npm cannot install both without a conflict. These versions are not compatible.

This is often due to:

• Peer Dependencies: A package declares that it needs a certain version of another package (a peer) to function correctly. If your project already has an incompatible version of that peer installed, an ERESOLVE error occurs.
• Transitive Dependencies: Your direct dependencies have their own dependencies. Also, those dependencies might clash. This creates a complex web where a conflict might not be immediately obvious in your top-level package.json.
• Outdated Packages: Using older versions of packages that haven’t been updated to be compatible with newer versions of their own dependencies or with the stricter npm resolution logic.

How to Diagnose the Specific ERESOLVE Conflict

Before attempting a fix, we recommend understanding the exact nature of the conflict. The error message itself often provides valuable clues, detailing the conflicting packages and their version requirements. However, you can use npm’s diagnostic tools for a clearer picture:

1. Review the Error Message: When the ERESOLVE error occurs, npm prints a detailed message. Look for sections like 'npm ERR! ERESOLVE unable to resolve dependency tree' and the subsequent lines that list the conflicting packages and their required versions. For instance, it might say 'found: react@18.0.0' but 'project-name@1.0.0 requires react@^17.0.0'.
2. Use npm ls for a Dependency Tree Overview: Run npm ls in your project’s root directory. This command will display the entire dependency tree. Conflicting packages are often highlighted or marked with warnings, indicating where the tree could not be fully resolved.
3. Use npm explain for Detailed Conflict Information: If the error message points to a specific package, use npm explain to see why npm installed (or tried to install) a particular version and which other packages depend on it. This can help trace the origin of the conflict. For example, to understand why a certain React version is causing issues, you might run:

   npm explain react

4. Check Peer Dependencies with npm view: For a specific package, you can inspect its declared peer dependencies using npm view peerDependencies --json. This helps confirm what versions it expects from its peers. For example:

   npm view @angular/core peerDependencies --json

Step-by-Step Fixes for npm ERESOLVE Errors

Once you understand the conflict, you can apply one of the following solutions. We recommend trying them in order, starting with the least disruptive.

1. Use --legacy-peer-deps (Temporary Workaround)

This flag tells npm to ignore peer dependencies during installation, reverting to the behavior of npm v6. It’s a quick way to get your project running, but it is not a lasting solution and can lead to runtime errors or unexpected behavior if packages genuinely rely on specific peer versions. Use this when you need to quickly bypass the error for development or testing, understanding its potential drawbacks.

1. Run the installation command with the flag:

   npm install --legacy-peer-deps

2. Expected result: npm will proceed with the installation, ignoring peer dependency conflicts. You should see a successful installation message, possibly with warnings about ignored peer dependencies.

2. Align Dependency Versions (The Lasting Solution)

This is the most solid solution. It involves manually adjusting the versions of conflicting packages in your package.json to find a set that is compatible across all your project’s dependencies.

1. Identify conflicting packages: Based on your diagnosis (from the error message or npm explain), pinpoint the exact packages and their required versions that are causing the conflict.
2. Adjust package.json: Edit your package.json file to use compatible versions. You might need to:
   • Downgrade a package: If a newer version of a package introduces a conflict, try an older, compatible version.
   • Upgrade a package: If an older package is causing a conflict with a newer, essential one, try updating the older package to a version that resolves the conflict.
   • Use exact versions: Instead of caret (^) or tilde (~) ranges, specify exact versions (e.g., "react": "17.0.2") to ensure consistency.

   Always consult the documentation or GitHub issues of the conflicting packages to find compatible versions.

3. Reinstall dependencies: After modifying package.json, delete node_modules and package-lock.json (or npm-shrinkwrap.json) to ensure a clean slate, then reinstall.

   rm -rf node_modules package-lock.json  # For macOS/Linux
   # For Windows, use: rmdir /s /q node_modules & del package-lock.json
   npm install

4. Expected result: A successful npm install without ERESOLVE errors. The dependency tree should now be consistent.

3. Clear npm Cache and Reinstall

Occasionally, a corrupted npm cache can lead to unexpected dependency resolution issues. Clearing the cache forces npm to redownload packages, which can resolve some obscure conflicts.

1. Clear the npm cache:

   npm cache clean --force

2. Remove node_modules and package-lock.json:

   rm -rf node_modules package-lock.json  # For macOS/Linux
   # For Windows, use: rmdir /s /q node_modules & del package-lock.json
   

3. Reinstall dependencies:

   npm install

4. Expected result: A clean installation. If the error was cache-related, it should now be resolved.

4. Update npm Itself

Newer versions of npm often include improvements to the dependency resolution algorithm and bug fixes. Updating npm might resolve conflicts that older versions struggled with.

1. Update npm globally:

   npm install -g npm@latest

2. Reinstall dependencies in your project: After updating npm, go back to your project directory and try a clean install.

   rm -rf node_modules package-lock.json  # For macOS/Linux
   # For Windows, use: rmdir /s /q node_modules & del package-lock.json
   npm install

3. Expected result: A successful installation with the updated npm.

What to Do If the Fix Still Fails

If you’ve tried the above steps and still encounter the ERESOLVE error, consider these additional troubleshooting avenues:

• Check Node.js Version: Ensure your Node.js version is compatible with your project’s dependencies. Some packages might require specific Node.js versions. You can use a tool like nvm (Node Version Manager) to easily switch Node.js versions.
• Permissions Issues: On macOS or Linux, if npm doesn’t have the necessary permissions to write to the node_modules directory or global npm directory, it can lead to errors. Try running the install command with sudo (e.g., sudo npm install). However, be cautious as this can lead to other permission issues later. A better long-term solution is to fix your npm permissions.
• Deep Dive into Transitive Dependencies: For very complex conflicts, you might need to manually inspect the package.json files of your direct dependencies to understand their sub-dependencies. This can be time-consuming but sometimes necessary to find the root cause.
• Report an Issue: If you believe the conflict is due to an incompatibility between widely used packages that should work together, consider reporting an issue on the GitHub repository of one of the conflicting packages.

How to Confirm the Error is Fixed

After applying a fix, it’s crucial to confirm that the ERESOLVE error is truly resolved and that your project is in a stable state:

1. Run npm install again: Execute npm install without any flags. A successful run, ending with a message like 'added X packages in Ys' and no ERESOLVE errors, indicates the problem is resolved.
2. Inspect the dependency tree with npm ls: Run npm ls to visually inspect the dependency tree. Look for any warnings or unmet peer dependencies that might still be present, even if the installation completed. A clean output suggests a healthy dependency tree.
3. Run Project Tests: If your project has automated tests, run them to ensure that the installed dependencies are functionally correct and haven’t introduced any runtime regressions.

Frequently asked questions

What does `npm ERESOLVE` mean?

The `npm ERESOLVE` error indicates a dependency conflict where npm cannot find a single set of package versions that satisfy all the requirements of your project and its dependencies, particularly concerning peer dependencies introduced in npm v7 and later.

How can I prevent `ERESOLVE` errors?

You can prevent `ERESOLVE` errors by regularly updating your project’s dependencies, being mindful of version ranges in your `package.json`, and using tools like `npm outdated` to identify packages that are far behind their latest versions.

When should I use `–force` instead of `–legacy-peer-deps`?

You should almost never use `–force`. While `–legacy-peer-deps` bypasses peer dependency checks, `–force` overrides all conflicts, including critical ones that could break your application or introduce security vulnerabilities. `–force` is a last resort for highly specific, known-safe scenarios, whereas `–legacy-peer-deps` is a safer temporary workaround for peer dependency issues.

Last updated 15 November 2026 · Editorial standards · Report an error