Skip to content
EVI Solutions

npm ERR! dependency conflict: how to resolve and install packages

Medium 15 min Updated:

Quick answer

The npm ERR! dependency conflict error occurs when two or more packages require different versions of the same dependency. The solution is to inspect the dependency tree, update or lock versions, or temporarily use the --legacy-peer-deps option. Ignoring warnings is not recommended as it can lead to unstable application behavior.

How to recognize the problem

  • npm install reports an ERESOLVE error
  • The message contains 'unable to resolve dependency tree'
  • Package installation fails even though it worked before
  • The application crashes due to incompatible package versions
  • npm warns about a peer dependency conflict

Most common causes

Incompatible peer dependencies

Two packages require different versions of the same peer dependency, so npm cannot find a common version.

Outdated packages in the project

Some packages in package.json are outdated and require older dependency versions that are no longer compatible with newer packages.

Manual editing of package-lock.json

If package-lock.json was manually edited or is missing, npm cannot properly resolve the dependency tree.

Using npm version 7+

Newer npm versions check peer dependencies more strictly, so errors that were previously hidden now appear.

Step-by-step fix

  1. 1

    Read the exact error message

    Run npm install and read the message carefully. npm usually states which package and which versions are in conflict. Based on that, you know which packages need to be updated or adjusted.

  2. 2

    Inspect the dependency tree

    Run npm ls <package-name> to see which versions are installed and who requires them. For a more detailed view, use npm ls --all. This helps you identify the source of the conflict.

  3. 3

    Update the problematic packages

    If the cause is an outdated version, try npm update <package-name> or manually change the version in package.json to a newer one. Then run npm install to check if the conflict is resolved.

  4. 4

    Delete node_modules and package-lock.json

    Sometimes leftover files are the source of the problem. Before deleting, make a backup of the package-lock.json file or check that the state is committed to git. Then delete the node_modules folder and the package-lock.json file, and run npm install again. This builds a fresh dependency tree.

  5. 5

    Use --legacy-peer-deps as a temporary solution

    If you cannot update packages immediately, run npm install --legacy-peer-deps. This option ignores peer dependency conflicts and installs packages as in older npm versions. Keep in mind that this can lead to instability.

  6. 6

    Use --force with caution

    The npm install --force option forces installation and can resolve stubborn cases, but it can break dependencies. Use it only if the previous steps failed and if you understand the risk.

  7. 7

    Check Node.js version compatibility

    Some errors are caused by an incompatible Node.js version with the packages. Check if your Node.js version meets the package requirements. If not, change the version using a version management tool.

  8. 8

    Use npm-check-updates to update

    Install the npm-check-updates tool globally and run ncu -u to automatically update all versions in package.json to the latest. Before that, commit changes and check compatibility, because ncu -u can move to new major versions. Then run npm install. This is useful for projects with many outdated packages.

If nothing helps

If all steps have been tried and the error persists, check if the problem is with the npm registry itself or the network. Sometimes it is enough to check the npm cache with the npm cache verify command, and if you suspect corruption, only then clean it with npm cache clean --force and try again. Also, consider using an alternative package manager such as Yarn, which has a different approach to dependency resolution. If that also fails, consult the package documentation or community. In team projects, be sure to inform colleagues about changes in package.json and package-lock.json so everyone has a consistent environment.

How to prevent it

  • Regularly update packages and check for outdated ones with `npm outdated`.
  • Use package-lock.json and commit it to git.
  • Avoid manually editing package-lock.json.
  • Test installation in a clean environment before sharing it with the team.

When to call a professional

If the dependency conflict repeats and affects team productivity, or if you are not sure which package versions are compatible, contact IT support. They can help analyze dependencies and establish a stable development environment.

Let us handle it Ask the AI IT assistant
Software and product development · Custom apps, SaaS and an MVP in 4 to 8 weeks

FAQ

What does npm ERR! dependency conflict mean?

It is an error that occurs when npm cannot find a package version that satisfies all requirements. It most commonly occurs due to a peer dependency conflict between two or more packages.

Is --legacy-peer-deps a safe solution?

This option temporarily solves the problem by ignoring peer dependency conflicts. However, it can lead to packages not working correctly if they are truly incompatible. Use it only as a temporary solution.

How can I prevent dependency conflicts in the future?

Regularly update packages, use package-lock.json, and avoid manual editing. Also, follow npm warnings and respond to outdated dependencies in time.

Share
Didn't find a fix?The AI IT assistant is available 24/7. Describe the problem or send a screenshot of the error and get instructions for your case.Ask the AI IT assistant