Version mismatch errors occur when npm cannot resolve conflicting version requirements between packages. Use --legacy-peer-deps for a quick fix, or update packages to compatible versions for a proper solution.
This error occurs when npm's dependency resolver cannot find versions that satisfy all requirements. Package A might need lodash@^3.0.0 while Package B needs lodash@^4.0.0—and there's no single version that satisfies both. Starting with npm 7, peer dependency conflicts became errors instead of warnings (as they were in npm 6). This stricter behavior catches potential runtime issues earlier but can make upgrading packages more challenging. The error often appears after updating a package, adding a new dependency, or upgrading npm itself from version 6 to 7+.
Bypass strict peer dependency resolution:
npm install --legacy-peer-depsThis reverts to npm 6's behavior where conflicts are warnings, not errors. It's a quick fix but may hide real compatibility issues.
To make it permanent (not recommended for all projects):
npm config set legacy-peer-deps trueRead the error message carefully. It shows exactly what conflicts:
npm ERR! ERESOLVE could not resolve
npm ERR! Found: [email protected]
npm ERR! peer react@"^18.0.0" from [email protected]This tells you react-dom@18 needs React 18, but you have React 17.
Upgrade packages to versions that work together:
# Check available versions
npm view react-dom versions
# Update to compatible versions
npm install react@18 react-dom@18Or downgrade the newer package:
npm install react-dom@17Sometimes stale dependencies cause conflicts:
rm -rf node_modules package-lock.json
npm cache clean --force
npm installThis resolves dependencies fresh without cached decisions.
Force specific versions for nested dependencies (npm 8.3+):
{
"overrides": {
"lodash": "4.17.21"
}
}This tells npm to use lodash 4.17.21 everywhere, regardless of what individual packages request.
Caution: This may cause runtime issues if packages truly need different versions.
Force installation ignoring all conflicts:
npm install --forceWarning: This can create broken installations. Only use for debugging or when you're certain the conflicts don't matter.
npm 6 vs npm 7+ behavior:
npm 6 treated peer dependency conflicts as warnings and installed anyway. npm 7+ treats them as errors by default. This is actually better—it catches incompatibilities before runtime.
For native modules (N-API, node-gyp):
If the error mentions native modules or Node.js version mismatches:
# Rebuild native modules
npm rebuild
# Or clear everything and reinstall
rm -rf node_modules
npm installIn CI/CD pipelines:
Use npm ci instead of npm install for consistent builds:
npm ci --legacy-peer-deps # If neededLong-term solution:
Rather than relying on --legacy-peer-deps, gradually update packages to compatible versions. Use npm outdated to identify what needs updating and test updates in a branch before merging.
npm ERR! code ENOAUDIT npm ERR! Audit endpoint not supported
How to fix "npm ERR! code ENOAUDIT - Audit endpoint not supported"
npm ERR! code EBADDEVENGINES npm ERR! devEngines.runtime incompatible with current node version
How to fix "npm ERR! code EBADDEVENGINES - devEngines.runtime incompatible with current node version"
npm ERR! code ETOOMANYARGS npm ERR! Too many arguments
How to fix "npm ERR! code ETOOMANYARGS - Too many arguments"
npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces
How to fix "npm ERR! code EINVALIDTAGNAME - tag names cannot contain spaces"
npm ERR! code E400 npm ERR! 400 Bad Request
How to fix "npm ERR! code E400 - 400 Bad Request" error