npm ERR! ERESOLVE unable to resolve dependency tree: what it means and the right fix
Two packages in your project want different versions of a shared package, usually React, ESLint or TypeScript, and since npm 7 that mismatch stops the install instead of printing a warning.
How to read the error
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR! react@"^19.0.0" from the root project
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0 || ^18.0.0" from [email protected]Read it as a sentence: you have react 19 (Found), but some-date-picker 4.2.1 says it only works with react 16 to 18 (peer … from). A peer dependency is a package a library expects you to provide, so it can share one copy with your app instead of bundling its own.
The real fixes, best first
- Upgrade the package that’s behind.
npm view some-date-picker peerDependenciesshows each version’s ranges; often a newer major already supports your React.npm outdatedlists what has updates. - Match versions instead. If the library has no compatible release yet, stay on the version it supports (for example
npm install react@18 react-dom@18) until it catches up. - Override, knowingly. If you have tested that it really works, tell npm in
package.json:
This is recorded in the project, so teammates and CI get the same result. Validate the file with the JSON formatter if npm complains about it."overrides": { "some-date-picker": { "react": "$react" } } - Swap the package if it looks abandoned (no release for years, open issues about your version).
What the flags really do
| Flag | Effect | Risk |
|---|---|---|
--legacy-peer-deps | Ignores peer dependencies completely, like npm 4–6 did | Silent runtime bugs if the versions really are incompatible; also skips peers you need |
--force | Installs anyway, picking versions even when they conflict | Can create a tangled lockfile; harder to undo |
overrides | Forces one specific version in one specific place | Lowest, because it’s explicit and reviewed |
If you do use --legacy-peer-deps, put legacy-peer-deps=true in the project’s .npmrc so CI behaves the same, and leave a note saying why.
“It worked yesterday”
- CI runs
npm ciwith a different npm version than your laptop. Checknpm -von both and pin it with"packageManager"orengines. - Someone deleted
package-lock.json, so npm re-resolved everything to the newest versions. Restore it from git and compare the old and new lockfile in a text diff to see what jumped. - A fresh
npx create-…template pulled the newest React before its plugins caught up. Matching versions (fix 2) is usually right for a week or two.
Getting npm ERR! code ENOENT instead? See npm ENOENT fixed. Build dying with error:0308010C:digital envelope routines::unsupported after a Node bump? See Node OpenSSL envelope error.
Related
Questions
Is it safe to use npm install --legacy-peer-deps?
Often it works, but it is a workaround: npm stops checking peer dependencies, so a real incompatibility will show up as a runtime bug instead of an install error. Prefer upgrading or an explicit override, and record the choice in .npmrc if you keep it.
What is the difference between --force and --legacy-peer-deps?
--legacy-peer-deps ignores peer dependencies entirely. --force still tries to install them but accepts conflicting versions. Both hide the problem; overrides in package.json is the explicit alternative.
Why did ERESOLVE start after upgrading npm?
Since npm 7, peer dependencies are installed and enforced automatically. Older npm only printed a warning, so conflicts that were always there now stop the install.
How do I find which package causes ERESOLVE?
Look at the line ending in 'from package@version' under 'Could not resolve dependency'. That package's peerDependencies range doesn't include the version shown under 'Found'. npm explain <package> shows who depends on what.
Published .