Build failed: npm ERR! ERESOLVE

What it means in plain English

The site never gets built. npm looked at package.json and could not pick versions that satisfy every package's peer dependencies. npm 7 and later treat that clash as a failed install. Vercel runs that install during the build, so the deploy stops with npm ERR! code ERESOLVE.

Likely causes

• Two packages ask for different versions of the same peer. The log names them under While resolving and Could not resolve dependency.
• The lockfile was created with a looser npm, and Vercel installs with a current npm that enforces peers.
• Someone added --legacy-peer-deps locally and did not tell Vercel to do the same.

How to fix it, step by step

1. Open the failed Vercel deployment and read the ERESOLVE block. Note the package that Found a version and the package that Could not resolve its peer.
2. Prefer a real version fix: upgrade or remove the package that demands the old peer, or pin the peer to a version both sides allow. Commit the updated package.json and lockfile.
3. If you must ship before that package is fixed, npm documents --legacy-peer-deps. It makes npm ignore peerDependencies the way npm 3 through 6 did. npm's own docs say this is not recommended, because it skips the peer contract.
4. To use that flag on Vercel, set installCommand in vercel.json at the repo root, or override Install Command in Project → Settings → Build and Deployment. Example: npm install --legacy-peer-deps. An empty installCommand skips install entirely, which is not what you want here.
5. Redeploy. A local node_modules folder is not uploaded, so the host has to install again.

How to check it worked

• The deployment log gets past "Installing dependencies" and finishes the build.
• The production URL loads the new deployment.

Sources

• https://docs.npmjs.com/cli/v11/using-npm/config#legacy-peer-deps (opens in a new tab)
• https://vercel.com/docs/project-configuration/vercel-json (opens in a new tab)