npm ERR! ERESOLVE could not resolve
npm ERR! While resolving: some-package@2.0.0
npm ERR! Found: react@18.2.0
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from another-package@1.5.0

What causes this

npm 7+ enforces strict peer dependency resolution by default. When two packages in your dependency tree require different versions of the same package, npm refuses to install rather than silently picking one. This is actually a safety feature — npm 6 used to just install whatever and hope for the best.

Common scenarios:

• You upgraded React 17 → 18 but a UI library still lists "peerDependencies": { "react": "^17.0.0" }
• A testing library needs one version of a package, your app needs another
• You’re installing a package that hasn’t been updated for your framework version

Fix 1: Use —legacy-peer-deps

npm install --legacy-peer-deps

This tells npm to behave like npm 6 — ignore peer dependency conflicts. It’s the quickest fix and usually safe. You can make it permanent:

# Add to .npmrc so the whole team uses it
echo "legacy-peer-deps=true" >> .npmrc

Fix 2: Check what’s actually conflicting

Before forcing anything, understand the conflict:

npm ls react

This shows the dependency tree for react. You’ll see which packages need which versions. Often the fix is just updating the outdated package:

npm update another-package
# or install the latest version
npm install another-package@latest

Fix 3: Use —force

npm install --force

This is more aggressive than --legacy-peer-deps — it forces installation even with conflicts and overwrites existing packages. Use this as a last resort.

Fix 4: Clean install

Sometimes the lockfile gets into a bad state:

rm -rf node_modules package-lock.json
npm install

If the conflict persists after a clean install, it’s a real version mismatch and you’ll need Fix 1 or Fix 2.

Fix 5: Use overrides (npm 8.3+)

Force a specific version for a transitive dependency:

{
  "overrides": {
    "react": "^18.2.0"
  }
}

This tells npm “use React 18 everywhere, even if a package asks for 17.” Only do this if you’ve tested that the package actually works with the newer version.

How to prevent it

• Keep dependencies updated regularly — small incremental updates cause fewer conflicts than big jumps
• Check a package’s peer dependencies before installing: npm info package-name peerDependencies
• Consider using pnpm which handles peer dependencies more gracefully
• When upgrading a major framework version, update all related packages at the same time