npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-package@2.0.0
npm ERR! node_modules/some-package
npm ERR!   some-package@"^2.0.0" from the root project

This error means a package you’re installing requires a specific version of another package, and your project has a different version.

What Peer Dependencies Are

A peer dependency is a package saying: “I don’t install this myself, but I need it to be there, and it needs to be version X.”

Example: A React component library might say “I need React 17 or 18.” If your project uses React 19, npm throws a peer dependency error.

Fix 1: Use —legacy-peer-deps (Quick Fix)

npm install --legacy-peer-deps

This tells npm to ignore peer dependency conflicts and install anyway. It’s the npm v6 behavior — less strict, usually works fine.

When to use: When you just want it to work and the package is probably compatible anyway.

Risk: The package might not work correctly with your version. Usually it does though.

Fix 2: Use —force

npm install --force

More aggressive than --legacy-peer-deps. Forces installation and overwrites any conflicts.

When to use: When --legacy-peer-deps doesn’t work.

Risk: Higher chance of runtime issues. Check that things work after installing.

Fix 3: Match the Required Version

The proper fix — install the version the package wants:

# Check what version is required
npm ls react

# Install the matching version
npm install react@18

When to use: When you can afford to change the dependency version.

Risk: Might break other packages that depend on your current version.

Fix 4: Use overrides (npm 8.3+)

Force a specific version for all packages in your project:

{
  "overrides": {
    "react": "19.0.0"
  }
}

Add this to your package.json, then run npm install.

When to use: When you know your version works and want to silence the error permanently.

Fix 5: Switch to pnpm or yarn

Both handle peer dependencies more gracefully:

# pnpm auto-installs peer deps
pnpm install

# yarn is also more lenient
yarn install

How to Prevent This

1. Check compatibility before installing: npm info some-package peerDependencies
2. Keep major dependencies updated: Most peer dep issues come from being 1-2 major versions behind
3. Use npx npm-check-updates to see what’s outdated

Common Scenarios

React version mismatch — Most common. A library wants React 18, you have React 19. Usually works fine with --legacy-peer-deps.

TypeScript version mismatch — Some packages pin specific TypeScript versions. --legacy-peer-deps almost always works.

ESLint plugin conflicts — ESLint plugins often have strict peer deps. Use --legacy-peer-deps or update ESLint.