Understanding and Resolving npm ERESOLVE Dependency Conflicts

Understanding and Resolving npm ERESOLVE Dependency Conflicts

An npm ERESOLVE error means npm couldn't build a dependency tree that satisfies all version rules — most often because of peer dependencies. Since npm 7, peer dependencies are handled strictly during install, so conflicts that previously installed “anyway” now fail fast.

That strictness reduces runtime surprises, but it can block installs when one package expects older versions than your project.

Quick Triage: Find the Actual Conflict

Before you force anything, identify who requires what. These commands usually pinpoint the culprit in under a minute.

npm -v
node -v

# show dependency chain
npm ls @tensorflow/tfjs
npm ls react

# show peer dependency requirements
npm view @tensorflow-models/handpose peerDependencies

# explain why a version was chosen
npm explain @tensorflow/tfjs

Why Peer Dependency Conflicts Happen

Peer dependencies are compatibility contracts. A library says: “I don't ship React / TFJS myself — you must provide a compatible version.” Conflicts happen when two packages demand incompatible version ranges.

• Package A requires @tensorflow/tfjs ^3, but your project installs @tensorflow/tfjs@4.
• A plugin requires react@^17, while your app is on react@18.
• You mixed majors in a package family (e.g. tfjs core v4, backends still v3).

How to Fix npm ERESOLVE (Safest → Most Aggressive)

1) Align Versions (Best Long-Term Fix)

Keep one compatible major across the entire dependency family. This is the fix that survives CI, deployments, and future upgrades.

// package.json (example: align tfjs family on v3)
{
  "dependencies": {
    "@tensorflow/tfjs": "^3.21.0",
    "@tensorflow/tfjs-backend-webgl": "^3.21.0",
    "@tensorflow/tfjs-backend-cpu": "^3.21.0",
    "@tensorflow-models/handpose": "^0.0.7"
  }
}

rm -rf node_modules package-lock.json
npm install

2) Use npm "overrides" (Controlled Forcing, npm 8+)

Use overrides when a transitive dependency pulls the wrong version. This is safer than --force, but you must test runtime behavior.

// package.json
{
  "overrides": {
    "@tensorflow/tfjs": "^4.0.0",
    "@tensorflow/tfjs-backend-webgl": "^4.0.0",
    "@tensorflow/tfjs-backend-cpu": "^4.0.0"
  }
}

rm -rf node_modules package-lock.json
npm install

3) --legacy-peer-deps (Fast Unblock, Less Safety)

Bypasses strict peer resolution and installs anyway. Good for quick experiments — risky as a default in production.

npm install --legacy-peer-deps

4) --force (Last Resort)

Forces an install even when npm knows the tree is inconsistent. Use only if you accept potential runtime breaks.

npm install --force

5) Clean Install Checklist (Fixes Weird Lockfile States)

rm -rf node_modules package-lock.json
npm cache verify
npm install

npm vs pnpm vs Yarn: Practical Differences

All three can hit peer conflicts, but they differ in speed, node_modules strategy, and how quickly they expose "hidden" dependency mistakes.

npm (v7+): strict by default

• Pros: catches incompatible peer combos early; predictable CI.
• Cons: blocks installs more often; people reach for flags.
• Best for: teams that want strict correctness over convenience.

pnpm: fast, disk-efficient, stricter dependency access

pnpm uses a global content-addressable store and links packages. Installs are typically faster and use less disk. Its stricter layout can reveal missing direct dependencies earlier.

corepack enable
corepack prepare pnpm@latest --activate

pnpm install

Yarn: strong workspaces tooling, flexible resolutions

Yarn is popular in monorepos. Depending on Yarn version/config it can feel more forgiving, but the big win is workspaces and its ability to pin versions via resolutions.

corepack enable
corepack prepare yarn@stable --activate

yarn install

# package.json (Yarn) -> "resolutions": { "react": "18.2.0" }

Conclusion

For production: prefer aligning versions or controlled overrides. Use --legacy-peer-deps to unblock quickly, and reserve --force for last resort. If installs are slow or the repo is large, pnpm is often a strong upgrade. If workspaces and strict pinning matter, Yarn is a good fit.

Copy/Paste Snippets

# safest: align versions
rm -rf node_modules package-lock.json
npm install

# controlled: overrides
# package.json -> "overrides": { "pkg": "version" }

# quick unblock
npm install --legacy-peer-deps

# last resort
npm install --force