AI Diagnostic Summary

npm ERR! code ERESOLVE

Well-Documented Error

This error matches known, documented patterns with reliable solutions.

Quick Fix (Most Common Solution)

Run npm install --legacy-peer-deps
Delete node_modules and package-lock.json, then reinstall

Seeing "npm ERR! code ERESOLVE"? This error can be frustrating, but it's usually fixable. It typically affects your development workflow or system. Below you'll find clear, step-by-step solutions to resolve this issue.

High confidence

What This Error Means

npm cannot resolve the dependency tree due to conflicting version requirements between packages.

Frequently documented in developer and vendor support forums.

Based on documented solutions and common real-world fixes.
Not affiliated with browser, OS, or device manufacturers.

New here? Learn why exact error messages matter →

Common Causes

Conflicting peer dependencies
Outdated package-lock.json
Incompatible package versions

How to Fix

Run npm install --legacy-peer-deps
Delete node_modules and package-lock.json, then reinstall
Update conflicting packages to compatible versions

Last reviewed: June 2026 How we review solutions

Didn't fix it? Get a personalised solution

Version note: Common in npm 7+ (Node 15+). npm 6 and earlier did not enforce strict peer dependency resolution.

Environment-Specific Commands

Linux / macOS

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

Windows (PowerShell)

Remove-Item -Recurse -Force node_modules, package-lock.json
npm cache clean --force
npm install --legacy-peer-deps

Quick Diagnostic Path

If npm ls shows a red "UNMET PEER DEPENDENCY" → Update the parent package that requires the conflicting peer
If Error mentions a specific version range conflict → Pin the conflicting dependency in package.json overrides (npm 8.3+)
If --legacy-peer-deps worked but runtime breaks → Use npm dedupe to flatten the tree, then test thoroughly

If This Still Fails, Check

Monorepo with workspaces: run npm install from the root, not from a nested package directory
CI/CD pipelines with stale caches: clear the npm cache in your pipeline config before install
Packages using peerDependenciesMeta may silently override — check package.json for optional peers

Using overrides to force a peer dependency version (package.json)

{
  "overrides": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

CI/CD Considerations

Fixing ERESOLVE Reliably Across GitHub Actions and CircleCI

CI pipelines surface ERESOLVE differently from local machines because they start with a clean filesystem and do not inherit your local ~/.npmrc, SSH keys, or environment variables. Understanding these differences prevents hours of debugging. In GitHub Actions, use the actions/setup-node action with cache: 'npm' to restore the npm cache efficiently. Always pin the Node version: node-version: '20.x'. Use npm ci instead of npm install — it respects the lockfile and fails on dependency drift rather than silently upgrading. For private package access, add your registry token via echo "//registry.npmjs.org/:_authToken=TOKEN" >> ~/.npmrc in a pipeline step. In CircleCI, the node orb handles caching automatically but its default cache key may not invalidate when package-lock.json changes — override it with a key that includes {{ checksum "package-lock.json" }}. When ERESOLVE appears only in CI, the first step is always to compare node --version and npm --version between local and CI output.

Optional follow-up

Some users ask whether saving fixes for recurring errors would be useful when the same issue appears again.

Was this explanation helpful?

Explanations are based on documented fixes, real-world reports, and common system behavior. GetErrorHelp is independent and not affiliated with software vendors, device manufacturers, or service providers.

Frequently Asked Questions

What does ERESOLVE mean?

ERESOLVE indicates npm cannot find a valid dependency tree that satisfies all package requirements.

Is --legacy-peer-deps safe?

It bypasses peer dependency checks, which may cause runtime issues but often resolves install problems.

Related Resources

Also Known As

npm install error
npm dependency error
node package manager error
npm ERR! message

Common Search Variations

"npm install not working"
"npm ERR how to fix"
"node modules error fix"
"npm install failed what to do"
"npm dependency conflict solution"
"why does npm install fail"

Related Errors

Still Stuck?

Paste a different error message or upload a screenshot to get help instantly.

Solutions are based on commonly documented fixes and may not apply in all situations.