VPS Tutorials
Fix npm ERESOLVE on a VPS: Peer Dependencies, npm ci and Locks (2026)
Read the conflict chain, select compatible versions and review lock changes. Rebuild cleanly and validate the application before deployment.

Deploying a Node.js, Next.js or coding-agent project may stop when npm install reports ERESOLVE unable to resolve dependency tree. Usually npm cannot build an acceptable dependency tree; inspect compatibility between a plugin's peerDependencies and its host library.
Read which version was found and which package requires which range, then make the smallest justified change. Keep package-lock.json and avoid making --force a default deployment option. A successful installation does not establish runtime compatibility.
Examples use npm 11, with the original documentation review dated 16 October 2026. Consult your version's documentation and repair in a development branch, builder or new release directory, away from the running application's dependencies.
| Log | Investigate | Avoid as an initial response |
|---|---|---|
ERESOLVE, Could not resolve dependency, peer | Version ranges, dependency origin and resolver settings | Repeated mirror/cache changes |
EAI_AGAIN, ETIMEDOUT | DNS, network, proxy and registry | Editing peer ranges |
EBADENGINE or engines warnings | Supported Node/npm versions | Assuming a peer conflict |
EACCES | User/directory permissions | Installing every dependency with sudo |
Killed, heap exhaustion | Memory and process/build limits | Upgrading dependencies as a memory fix |
Several problems can surface successively. Follow the actual failing phase. If installation succeeds and build is killed, see Next.js build OOM.
An illustrative project selects React 17 but a React DOM release requires React 18:
Found: [email protected]
Could not resolve dependency:
peer react@"^18.2.0" from [email protected]
Extract:
- The selected host version:
[email protected]. - The required range:
[email protected]needsreact@^18.2.0. - The requesting package: determine whether
react-domis direct or transitive.
Downloading another copy is not an automatic solution. peerDependencies expresses host/plugin compatibility. npm has installed peers by default since v7 and can reject unsatisfied constraints; see peerDependencies. React 17/18 here reproduces historical constraints, not a 2026 production recommendation. Choose real versions from framework support, security maintenance and functional validation.
At the correct repository root, collect these read-only checks locally, in CI, in the Docker build and on the VPS:
pwd
git status --short
node --version
npm --version
npm pkg get engines packageManager
npm config get registry
npm config get legacy-peer-deps
npm config get strict-peer-deps
npm config get omit
- Compare commit,
package.jsonand lockfile. - Check Node/npm against project declarations, team policy and builder image.
- Identify the original npm/pnpm/Yarn workflow.
- Check whether local
legacy-peer-deps=truediffers from the server. - Inspect
NODE_ENV=productionand relevant npm environment settings in CI.
packageManager does not guarantee every build system selects that tool version. Read actual logs before globally upgrading npm. Project/user/global configuration, CLI and environment can all influence resolution; SSH and deployment users may differ. See .npmrc. Share only required redacted settings, never registry tokens or full credential-bearing configuration.
Use the specific version in the error, continuing the historical example:
npm view [email protected] peerDependencies engines --json
npm view [email protected] engines --json
Do not apply an unversioned npm view react-dom peerDependencies result to an old release; it may describe latest. npm view reads registry metadata; see npm view. Use the project's registry for private packages instead of sending their names to unrelated services.
For an existing installation, inspect its origin:
npm explain react
npm ls react react-dom --all
npm explain explains installed dependencies. Without a finished install or node_modules, results may be incomplete. Use the error, root package.json, workspace configuration and lockfile instead. See npm explain. npm ls may return nonzero for missing/invalid packages: retain that evidence. See npm ls.
| Choice | When suitable | Verify |
|---|---|---|
| Upgrade plugin, retain host | Maintained plugin supports this host | API, configuration and behavior |
| Change host and related packages | Framework migration is acceptable | Migration requirements, build and workflows |
| Replace abandoned plugin | No compatible maintained release | Features, data and configuration migration |
| Temporary existing compatibility policy | Documented history, tests and exit plan | CI consistency, runtime risks and removal |
Do not downgrade the framework merely because one peer fails: the application may use new APIs and other plugins may require them. Find a mutually supported combination.
This minimal package.json intentionally conflicts in an isolated demonstration project; never replace the real project with it:
{
"name": "vps-eresolve-proof",
"version": "1.0.0",
"private": true,
"dependencies": {
"react": "17.0.2",
"react-dom": "18.2.0"
}
}
In that demo directory, this enters dependency resolution:
npm install --package-lock-only --ignore-scripts
For that demo only, change dependencies.react to 18.2.0, retain react-dom as 18.2.0, then run:
npm install --package-lock-only --ignore-scripts
npm ci --ignore-scripts
npm ls react react-dom --depth=0
The original article reports testing in a separate temporary directory with Node.js 24.21.0 / npm 11.19.0: ERESOLVE before the change; successful lock generation and npm ci afterward; both direct packages at 18.2.0; and no lockfile rewrite by npm ci.
That historical check disabled lifecycle scripts and established only an installable demo tree. Real projects still need their required scripts, build and functional checks; --ignore-scripts is not a full deployment. See npm install options.
Repair package.json and its lockfile in a reviewable environment. Deploy the verified declarations, lock and configuration through a clean install.
npm ci requires a lockfile and fails on declaration mismatch instead of repairing it. It writes neither package.json nor the lockfile, and removes existing node_modules first. See npm ci.
- Run it outside the active application directory to avoid dependency replacement during service.
- Resolve lock mismatch in the build workflow instead of improvising npm install on production.
- A conflicting peer tree can still fail with npm ci.
Review the real repository diff:
git diff -- package.json package-lock.json
Version the lockfile. Large unrelated changes after a small fix warrant checking npm version/configuration and accidental lock deletion before accepting them. See package-lock.json. In workspaces, maintain the shared lock at the agreed root, not a second unused lock in a subdirectory.
| Option | Effect | Establishes compatibility? |
|---|---|---|
--legacy-peer-deps | Ignores peer constraints when designing the tree | No |
--force | Relaxes several safeguards, including conflicting root peers | No; broader than peers |
--omit=peer | Omits peer unpacking on disk but still designs a satisfying tree | Not a conflict bypass |
See npm configuration. Fix versions first; an error's suggested retry flag is not a universal global policy.
For a justified legacy exception, record the reason, affected combination, tests and removal conditions. Tree-shaping flags used to generate the lock generally need consistent CI settings. Store reviewed nonsecret policy in project .npmrc, never registry tokens. Removing a flag while retaining the old lock does not establish strict-mode recovery: revalidate resolution and clean installation.
It selects versions again and may avoid one conflict while introducing unrelated updates. Retain the original and inspect changes in development to identify the actual repair.
No. overrides changes selections but does not make APIs compatible or arbitrary ranges valid. Check scope/direct-dependency limits in overrides and validate the application.
Not an explicit version conflict. Investigate cache integrity/metadata only with evidence. See npm's cache integrity guidance.
omit controls what lands on disk, not a blanket removal of resolution constraints. Builders may require TypeScript/bundlers; distinguish build and runtime stages.
Require the full conflict chain, compatible ranges, minimal dependency diff and clean installation without temporary bypass. Then run existing build/type/critical-workflow checks. A retained exception needs its impact and exit plan.
- Record actual Node/npm, commit and resolver configuration.
- Clean install succeeds with no unexplained invalid/missing dependencies.
- Existing build/checks and business tests pass; the demo does not replace project validation.
- Declarations, lock and nonsecret configuration form a reviewed change; explain unrelated updates.
- Prepare a new release/CI artifact, health-check before switching and retain the previous artifact/lock.
- Roll back code, dependency artifacts and configuration together, not just package.json with newer node_modules left behind.
The result must be a reproducible compatible application, not merely disappearance of ERESOLVE.