npm install 시 ERESOLVE unable to resolve dependency tree

Introduction

If you have upgraded to npm 7 or later, you have likely encountered the dreaded ERESOLVE unable to resolve dependency tree error. This error replaced the more lenient behavior of npm 6 and catches many developers off guard. In this post, I will explain why this happens and how to fix it.

Environment

node --version
# v20.11.0

npm --version
# 10.2.4

This issue is specific to npm 7+ which introduced stricter dependency resolution.

Problem

When running npm install, you see the following error:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.0.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-legacy-lib@2.1.0
npm ERR! node_modules/some-legacy-lib
npm ERR!   some-legacy-lib@"^2.0.0" 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

The key information here is that your root project requires react@^18.0.0 but a dependency requires react@^17.0.0. These are incompatible peer dependencies.

Analysis

npm 7+ changed the default behavior for peer dependency resolution:

• npm 6: Silently installed peer dependencies, even if they conflicted
• npm 7+: Refuses to install when peer dependency conflicts are detected

This is actually better behavior because it prevents runtime errors from version mismatches. However, it causes friction during development when third-party packages have not updated their peer dependency declarations.

The conflict matrix looks like this:

Root project:
  react: ^18.0.0

some-legacy-lib@2.1.0:
  peerDependencies:
    react: ^17.0.0

Resolution: IMPOSSIBLE (17.x and 18.x are not compatible with ^17.0.0)

Solution

Solution 1: Use --legacy-peer-deps (quick fix)

npm install --legacy-peer-deps

This tells npm to behave like npm 6 and skip peer dependency validation. Use this as a temporary measure.

Solution 2: Use --force (nuclear option)

npm install --force

This forces installation even with conflicts, but may cause runtime issues.

Solution 3: Configure in .npmrc (project-wide)

echo "legacy-peer-deps=true" > .npmrc

# .npmrc
legacy-peer-deps=true

Solution 4: Find and update conflicting packages (proper fix)

# Check which packages have peer dependency issues
npm ls --all 2>&1 | grep -i "peer dep"

# Update the problematic package
npm update some-legacy-lib

# Or find an alternative package
npm search react-component --long

Solution 5: Use overrides in package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.2.0",
    "some-legacy-lib": "^2.1.0"
  },
  "overrides": {
    "some-legacy-lib": {
      "react": "$react"
    }
  }
}

The $react syntax tells npm to use the same version of React that is defined in the root project's dependencies.

Lessons Learned

1. Always check npm ls before installing new packages to understand your dependency tree
2. Use --legacy-peer-deps in CI/CD if you cannot immediately resolve conflicts
3. Prefer overrides over force-installing - overrides give you more control
4. Maintain a .npmrc in your repository with consistent settings across the team
5. Consider switching to pnpm or yarn if dependency management becomes too painful with npm

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.