How to Fix npm ERR! code ERESOLVE — Copy-Paste Diagnostic Runbook from the Error Text

npm ERR! code ERESOLVE 30-Second Fix Runbook — Diagnose by Copy-Pasting the Error Text

Got red text in the console, the build is stuck, and someone upstairs is asking when the deploy will land? We'll save the concepts for the bottom. First, find the exact phrase on your screen in the table below. One-second match → 30-second diagnosis → one-line copy-paste recovery.

1. Exact-match classification table for the error text

Find the line that actually printed in your console, as-is.

The most important lines are Could not resolve dependency: and Conflicting peer dependency:. They contain the conflicting package name and the required version.

2. 30-second decision tree

Start by checking your npm version.

npm -v

npm below 7 (6.x) → ERESOLVE almost never appears. (If you're seeing this error, 99% chance you're on npm 7+)
npm 7+            → auto-installs peer deps + strict checks. That's the cause.
                ↓
Find the conflict line in the error message:
  "Could not resolve dependency: peer X@\"range\" from Y"
  → conflicting package = Y, problem peer = X, required version = range
                ↓
        ┌───────────────┴───────────────┐
   ① Demo / urgent build           ② Production / long-term maintenance
   "Just make it run"              "The next person must get the same install"
        ↓                              ↓
   §3: legacy-peer-deps            §4: pin versions with overrides

One-line summary: Work around if you're in a hurry; pin if you want it done right. A workaround is never a root-cause fix.

3. Just make it run — legacy-peer-deps vs force comparison

These two flags get the install through right now. If you reach for --force without knowing the difference, you'll have a bigger incident next week.

# 단일 peer 충돌, 일단 빌드만 돌리고 싶을 때
npm install --legacy-peer-deps

# 최후의 수단 (무엇이 깔릴지 보장 안 됨)
npm install --force

If you don't want to type the flag every time, you can bake it into the project.

# .npmrc
legacy-peer-deps=true

⚠️ Neither is a root-cause fix. The peer conflict is still there, and a different version can land on a teammate's machine or in CI. For production, go to §4 and pin the version with overrides.

4. Fix it properly — version-pinning runbook with overrides

4-1. Trace who requires the conflicting peer

# 예: react 버전 충돌이면
npm ls react

my-app@1.0.0
├── react@18.3.1
└─┬ some-old-lib@2.1.0
  └── react@"^17.0.0"   ← this is the culprit

This shows you immediately, as a tree, which package is asking for the old version.

4-2. Force-pin with package.json overrides (npm 8.3+)

This pins even transitive dependencies to a specific version.

{
  "overrides": {
    "react": "18.3.1",
    // nest if you only want to change react under a specific package
    "some-old-lib": {
      "react": "18.3.1"
    }
  }
}

Yarn does the same thing with resolutions.

// yarn (package.json)
{
  "resolutions": {
    "react": "18.3.1"
  }
}

After applying, wipe the lockfile and node_modules clean and reinstall for it to take effect.

rm -rf node_modules package-lock.json
npm install

4-3. If that still fails, clean the cache too

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

A note from the trenches: You hit this pattern constantly during React 18→19 migrations. When an old UI library insists on peer react@"^17", we opened an upgrade PR for the library, and until it merged we pinned react with overrides so the whole team installed the same version. Projects that just stuck --legacy-peer-deps in and moved on got a slightly different version in CI a few weeks later and hit "it worked on my machine" twice.

5. yarn / pnpm use different commands

The same peer conflict needs different hands depending on the package manager.

pnpm example:

// package.json
{
  "pnpm": {
    "overrides": {
      "react": "18.3.1"
    }
  }
}

pnpm defaults to a strict peer policy, so conflicts surface more readily than with npm. In a pinch, work around with pnpm install --no-strict-peer-dependencies—again, that's temporary.

6. Recurrence-prevention checklist

If you never want to see this red text again, bake the following in.

1) Pin versions (package.json)

{
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=10.0.0"
  }
}

2) Unify the Node version (.nvmrc)

20.11.0

3) In CI, use ci, not install

# install: can update the lockfile (breaks reproducibility)
# ci: reproduces the lockfile exactly; fails immediately on mismatch
npm ci

npm ci reproduces package-lock.json 100% as-is, so it stops "works locally, fails in CI."

Copy-paste command cheat sheet

npm -v                                  # 1) check version (ERESOLVE is expected on 7+)
npm ls <package-name>                   # 2) trace the conflicting culprit
npm install --legacy-peer-deps          # 3) temporary workaround if you're in a hurry
# after adding overrides to package.json ↓  # 4) root-cause fix
rm -rf node_modules package-lock.json
npm install
npm cache clean --force                 # 5) if that still fails, cache too

References: official docs

The primary sources for the behavior, settings, and errors covered in this post are the official docs below. Check them for version-specific options and exact behavior.

• Node.js official docs

FAQ

Q. Should I use --legacy-peer-deps or --force? A. Use --legacy-peer-deps if you only need a short workaround for a single peer conflict. --force overwrites every conflict and can install unintended versions—last resort only. Neither is a root-cause fix, so for production pin the version with overrides.

Q. Do I need to fix npm WARN ERESOLVE overriding peer dependency? A. No. WARN is not an error—it's an optional peer warning. The install completes normally and the build does not stop. You can ignore it and continue.

Q. I added overrides but they aren't taking effect. A. That's the lockfile cache. Delete with rm -rf node_modules package-lock.json, then npm install again for it to apply. Also check that you're on npm 8.3+ (npm -v). Older versions don't support overrides.