[SOLVED] npm ERR! ERESOLVE unable to resolve dependency tree in npm install

When running npm install or pulling a new dependency into a Node.js project, the execution halts with: npm ERR! code ERESOLVE and npm ERR! ERESOLVE unable to resolve dependency tree. Starting with npm version 7, the package manager automatically attempts to install peer dependencies and enforces strict semantic version compatibility trees.

Step-by-Step Solution

1. 1

   Step 1: Analyze the Conflicting Dependency Tree Branch

   Examine the error stack printed in your terminal. npm shows the precise mismatch causing the lockup:

   PLAINTEXT Copy

   Could not resolve dependency:
   peer react@"^17.0.0" from legacy-ui-lib@1.2.0
   node_modules/legacy-ui-lib
     legacy-ui-lib@"^1.2.0" from the root project
   

   Here, the root project requires React 18+, but the legacy UI package specifies an incompatible peer dependency on React 17.

2. 2

   Step 2: Bypass Peer Dependency Trees with --legacy-peer-deps

   The --legacy-peer-deps flag tells npm to ignore conflicting peerDependencies, restoring the classic behavior of npm v6:

   BASH Copy

   npm install --legacy-peer-deps
   

   To persist this across CI/CD runners (GitHub Actions, Vercel, Netlify), declare it in your local .npmrc:

   INI Copy

   # .npmrc
   legacy-peer-deps=true
   

3. 3

   Step 3: Pin Uniform Versions via package.json overrides

   For a clean, deterministic package resolution without bypassing validations, declare an overrides block in package.json:

   JSON Copy

   {
     "name": "my-app",
     "dependencies": {
       "react": "^18.3.1"
     },
     "overrides": {
       "legacy-ui-lib": {
         "react": "$react"
       }
     }
   }
   

   Delete your lockfile and reinstall:

   BASH Copy

   rm -rf package-lock.json node_modules
   npm install
   

Frequently Asked Questions

What is the operational difference between --legacy-peer-deps and --force?

--legacy-peer-deps ignores peerDependency graph collisions entirely. --force aggressively overwrites conflicting modules in node_modules, frequently causing subtle runtime bugs.

Is --legacy-peer-deps safe to deploy to production?

Yes, provided your application builds and passes automated unit tests, as most minor/major peer mismatches maintain backward-compatible core APIs.