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.

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:
- Run
npm installwith the same npm major, registry configuration and OS/CPU family as the CI runner, then commit the regenerated lock. - Never patch the lock by hand, and never run
npm installin CI to "make it pass" - that turns a deterministic install into a silent mutation of a committed artifact. - When only a range changed, use
npm install --package-lock-only, which updates the lock without touchingnode_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.
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 treeMinimal reproduction, worth keeping in a scratch repo because it makes the rule visible:
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 filelockfileVersion 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
| Command | Reads lock | Writes lock | Installs node_modules | Exit on mismatch |
|---|---|---|---|---|
| npm ci | yes, required | never | yes, after deleting existing | yes, code 1 |
| npm install | yes, if present | yes | yes | no, it resolves |
| npm install --package-lock-only | yes | yes | no | no, it resolves |
| npm ci --omit=dev | yes | never | yes, prod only | yes |
| npm ci --ignore-scripts | yes | never | yes, no lifecycle | yes |
| Message fragment | Meaning | Typical trigger |
|---|---|---|
| Missing: pkg@1.2.3 from lock file | manifest requires what the lock lacks | dependency added, lock not committed |
| Invalid: lock file's pkg@1.0.0 does not satisfy pkg@1.2.3 | lock holds an older resolution | range bumped, lock stale |
| can only install with an existing package-lock.json | no lock at all | fresh clone, lock gitignored |
| not in sync (workspaces) | a workspace manifest changed | monorepo partial commit |
| Lockfile version | Written by | Structure | Notes |
|---|---|---|---|
| 1 | npm 5 and 6 | dependencies tree | npm ci reads it, no packages map |
| 2 | npm 7 and 8 | packages plus dependencies | bridge for older npm |
| 3 | npm 9 and later | packages only | smaller, 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:
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 ciDeleting 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:
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-onlyKeep 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:
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 --forceCache ~/.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:
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, intentionallyRegenerate 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:
npm ci --workspace apps/web --include-workspace-root
npm install --package-lock-only --workspaces # keep every entry consistentA 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 installinside CI to fix it. It passes and mutates the lock on the runner only; the next clean clone fails again.--legacy-peer-depsas a permanent flag. It changes peer resolution, so machines with and without it produce different locks.--force.npm ci --forcecan 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
packagesmap contains. Upgrade the runner rather than downgrading the lock. package-lock=falseor the lock in.gitignore. Common in repos scaffolded from a template that also setshrinkwrap=false;npm cithen has nothing to replay.- A stale
yarn.lockorpnpm-lock.yamlbeside it. Editors and some CI images pick the wrong one; keep a single lock per project. file:andlink: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 documentationThe Node.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Node.js guides
All Node.js guidesStripe webhooks: no signatures found matching the expected signature
Verification needs the exact bytes Stripe sent and the endpoint's own secret. Fix parser order, proxy re-encoding and edge runtime crypto.
pnpm: Ignored build scripts and how to approve them
A skipped postinstall leaves native modules empty. Approve the packages once in committed config, then verify the build instead of allowing everything.
Node.js 26 upgrade: rmdir, native addons and removed flags
Three breaks stop a deploy: rmdir with recursive throws, the transform-types flag is gone, and the module ABI moved to 147.
Prisma P2002: Unique constraint failed
The database rejected a duplicate key. Replace check-then-insert with upsert or catch the code deliberately, and read meta.target for the culprit.
More in Node.js
All Node.js guidesThe guides filed next to this one in Node.js, in library order.