Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

npm ci: the lock file is out of sync and how to fix it correctly

The lock and the manifest disagree, and CI stops before installing. Regenerate on the same npm major and keep platform entries.

~6 min readNode.js
#npm#Node.js#CI#Package Managers
A manifest sheet and a lock sheet held apart by clamps with one misaligned dependency slot in amber

Introduction & Quick Summary

npm ci stops with npm error npm ci can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with npm install before continuing. and then lists one or more Missing: or Invalid: entries. Nothing is installed, the exit code is 1, and a CI job that passed yesterday fails today although no dependency was intentionally changed.

The cause is narrow: npm ci is a read-only installer. It does not calculate a dependency graph, it replays the one stored in the lock, and before replaying it compares the root manifest with the root entry of the lock (packages[""] in lockfileVersion 2 and 3). Any spec that differs - a new package, a bumped range, a removed line, a dependency moved to devDependencies - makes the two disagree, and npm fails fast instead of guessing.

The fix, applied in the right place:

  1. Run npm install with the same npm major, registry configuration and OS/CPU family as the CI runner, then commit the regenerated lock.
  2. Never patch the lock by hand, and never run npm install in CI to "make it pass" - that turns a deterministic install into a silent mutation of a committed artifact.
  3. When only a range changed, use npm install --package-lock-only, which updates the lock without touching node_modules.

Below: the mechanics behind that comparison, six situations that produce a mismatch even when package.json looks unchanged, and the version traps that make the error return after a clean fix.

Core Mechanics, Signatures & Reproducible Setup

npm ci has one hard precondition and a small surface: an existing lock, a lock that agrees with package.json, node_modules deleted before installation, and no write to the lock ever. That last point is why the failure is loud - there is no code path in which npm ci repairs the mismatch itself.

bash
npm ci # strict: lock must match package.json npm ci --omit=dev # skip devDependencies (npm 8+) npm ci --ignore-scripts # no lifecycle scripts npm ci --workspace app # one workspace of a monorepo npm install --package-lock-only # update lock only, no node_modules npm install --package-lock-only --omit=optional # repair platform drift npm ls --all --package-lock-only # validate the recorded tree

Minimal reproduction, worth keeping in a scratch repo because it makes the rule visible:

bash
mkdir ci-repro && cd ci-repro && npm init -y npm install --save-exact left-pad@1.3.0 # lock records 1.3.0 npm pkg set dependencies.left-pad='^2.0.0' # manifest moves, lock does not npm ci # npm error Missing: left-pad@2.0.0 from lock file

lockfileVersion 3, the default since npm 9, keeps only packages, keyed by install path, with "" as the project root. Version 2 keeps packages plus a legacy nested dependencies tree for npm 6 consumers. The comparison is over specifications, not resolved versions, so "fastify": "^5.2.0" in the manifest and the same string under packages[""] are equal even when 5.2.1 was installed; change the range and the key fails as Missing: or Invalid:.

Key Comparison Table

CommandReads lockWrites lockInstalls node_modulesExit on mismatch
npm ciyes, requiredneveryes, after deleting existingyes, code 1
npm installyes, if presentyesyesno, it resolves
npm install --package-lock-onlyyesyesnono, it resolves
npm ci --omit=devyesneveryes, prod onlyyes
npm ci --ignore-scriptsyesneveryes, no lifecycleyes
Message fragmentMeaningTypical trigger
Missing: pkg@1.2.3 from lock filemanifest requires what the lock lacksdependency added, lock not committed
Invalid: lock file's pkg@1.0.0 does not satisfy pkg@1.2.3lock holds an older resolutionrange bumped, lock stale
can only install with an existing package-lock.jsonno lock at allfresh clone, lock gitignored
not in sync (workspaces)a workspace manifest changedmonorepo partial commit
Lockfile versionWritten byStructureNotes
1npm 5 and 6dependencies treenpm ci reads it, no packages map
2npm 7 and 8packages plus dependenciesbridge for older npm
3npm 9 and laterpackages onlysmaller, default today

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Mixed npm majors silently rewrite the lock

npm 9 writes version 3 and prunes the legacy tree; npm 7 rewrites it back to 2. A commit from each machine produces churn on every install. Pin the toolchain so a wrong runner fails before the comparison:

{ "engines": { "node": ">=22.11 <23", "npm": ">=10.9" }, "packageManager": "npm@10.9.2" }

With engine-strict=true in .npmrc, the error becomes about the runtime, which is the one you can act on. Corepack does not manage npm's own version in every setup, so also print npm --version in CI.

2. Hand-edited and partially committed locks

The most common real cause is a lock that was never committed, or committed from a branch where the manifest differed. Check what git holds, not what your working tree holds:

bash
git status --short package.json package-lock.json git stash push --include-untracked && npm ci && git stash pop # regenerate deterministically and commit both together rm -rf node_modules package-lock.json npm install --package-lock-only && npm ci

Deleting the lock is acceptable in a library, where ranges are the contract. In an application it is not free: every patch release since the last generation enters the tree. Prefer --package-lock-only on the existing lock.

3. Optional platform binaries and the OS trap

esbuild, rollup, sharp, @swc/core and lightningcss ship one native package per platform through optionalDependencies. A lock generated with --omit=optional - or with npm_config_omit=optional exported in a shell profile - lacks the entry the runner needs, and the failure looks unrelated:

bash
npm ci # > esbuild: failed to install correctly, please delete node_modules/esbuild and try again npm config get omit # must not list optional unset npm_config_omit npm install --package-lock-only

Keep the platform entries in the lock and let npm skip the ones that do not match os and cpu at install time. Deleting them to shrink the diff is what breaks the next runner.

4. Docker and CI: copy the pair, install once

A Dockerfile that copies package.json alone and runs npm ci after adding a dependency fails exactly like this. Copy both files in one layer, before the source copy, so the cache survives code edits:

dockerfile
FROM node:22-alpine AS deps WORKDIR /app COPY package.json package-lock.json .npmrc ./ RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force

Cache ~/.npm in CI keyed on the lock hash, not on package.json, and keep --prefer-offline: it validates integrity from the cache and changes nothing about the sync check.

5. Private registries and rewritten resolved URLs

npm ci installs from the resolved URL in the lock, so a lock generated against the public registry and installed behind a private mirror fails on a tarball 404 - the same class of problem, since the lock encodes its environment:

bash
npm config set @acme:registry https://npm.pkg.github.com npm config set replace-registry-host "npmjs" npm install --package-lock-only # rewrite resolved and integrity once, intentionally

Regenerate after changing a registry, and never let always-auth=true reach a project .npmrc that ends up in an image.

6. Workspaces: one root lock covers every manifest

The single root lock holds one packages entry per workspace, so editing apps/web/package.json invalidates it. Running npm ci inside the workspace is a frequent mistake; npm walks up to the lock but compares against the nearest manifest, and the reported package names look unfamiliar:

bash
npm ci --workspace apps/web --include-workspace-root npm install --package-lock-only --workspaces # keep every entry consistent

A workspace manifest committed without the root lock is edge case 2 in monorepo form, and it is worth a pre-commit check that fails when git status shows only one of the pair.

Common Compilation/Runtime Mistakes & Version Gotchas

  • npm install inside CI to fix it. It passes and mutates the lock on the runner only; the next clean clone fails again.
  • --legacy-peer-deps as a permanent flag. It changes peer resolution, so machines with and without it produce different locks.
  • --force. npm ci --force can install a tree the lock does not describe. There is no supported CI use.
  • npm 6 runners. npm 6 reads version 2 through the legacy tree; when a later npm pruned it, the runner reports missing packages the packages map contains. Upgrade the runner rather than downgrading the lock.
  • package-lock=false or the lock in .gitignore. Common in repos scaffolded from a template that also set shrinkwrap=false; npm ci then has nothing to replay.
  • A stale yarn.lock or pnpm-lock.yaml beside it. Editors and some CI images pick the wrong one; keep a single lock per project.
  • file: and link: dependencies. They are recorded as paths, so a CI checkout without that path fails before the install starts.

To find the offending key quickly, diff the two committed files in Text Diff: the packages[""] block against the manifest's dependency blocks usually shows it in one screen. To read the resolved graph or one packages entry without an editor, paste the lock into JSON Formatter.

Primary references: the npm ci documentation states the lock precondition and the no-write rule, and the package-lock.json reference documents lockfileVersion and the packages map the comparison reads.

Official references

primary documentation

The Node.js documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Node.js guides

More in Node.js

All Node.js guides

The guides filed next to this one in Node.js, in library order.