Symptoms & Diagnosis
The npm ERR! code ERESOLVE error is a common headache for developers using Node.js versions 7 and above. It signifies a “Peer Dependency Conflict,” meaning npm cannot automatically decide which version of a package to install because different dependencies are asking for incompatible versions.
You will typically see this error when running npm install or npm update. The terminal output will display a “Conflicting peer dependency” tree, highlighting exactly where the version mismatch occurs between your root project and its sub-dependencies.
| Symptom | Primary Cause |
|---|---|
| npm ERR! code ERESOLVE | Incompatible peer dependency versions between two or more packages. |
| Could not resolve dependency | The dependency tree is broken and npm 7+ defaults to strict resolution. |
| Conflicting peer dependency | Package A requires React 17, while Package B requires React 18. |
Troubleshooting Guide
There are several ways to bypass or fix the ERESOLVE error. The best approach depends on whether you want a quick fix or a clean, long-term solution.
Method 1: Using the Legacy Peer Deps Flag
In npm versions prior to v7, peer dependency conflicts were ignored by default. You can revert to this behavior using the --legacy-peer-deps flag. This is the most common and safest “quick fix.”
npm install --legacy-peer-depsMethod 2: Using the Force Flag
The --force flag tells npm to ignore the conflict and fetch the packages anyway. Unlike legacy-peer-deps, this might result in multiple versions of the same package being installed in your node_modules.
npm install --forceMethod 3: Manual Conflict Resolution
For a production-grade fix, you should manually update the version in your package.json. Look at the error log provided by npm to see which package is causing the conflict and update it to a compatible version.
# Example: If a package requires a newer version of React
npm install react@latest react-dom@latestMethod 4: Clean Install
Sometimes, a corrupted package-lock.json causes resolution errors. Deleting the lock file and the node_modules folder can force a fresh resolution.
rm -rf node_modules package-lock.json
npm installPrevention
To avoid ERESOLVE errors in the future, keep your dependencies updated regularly. Outdated packages are the primary cause of peer dependency conflicts as they often lag behind the latest framework versions.
Use npm outdated to identify packages that need attention. Additionally, consider using tools like npm-check-updates to keep your package.json synchronized with the latest stable releases.
If you are working in a team, ensure everyone is using the same version of Node.js and npm. This prevents “it works on my machine” scenarios where one developer’s npm version handles resolution differently than another’s.