With npm, why does `npm ci` in a CI job fail right after a teammate adds a dependency to `package.json`, and what fixes it?
answer
- a frozen install never writes
- two files must agree
- the 'in sync' usage error
- Missing: name@version from lock file
- which command rewrites the lock
basics
~20 snpm ci installs exactly what package-lock.json records and never writes it, so when package.json declares a dependency the lock lacks it exits with an out-of-sync error. Run npm install locally and commit the updated lock.
solid answer
~40 s`npm ci` is npm's clean install for automated environments. It requires an existing `package-lock.json`, builds the tree `package.json` asks for, compares it with the lock, and on any difference exits with "`npm ci` can only install packages when your package.json and package-lock.json are in sync", listing each `Missing:` or `Invalid:` entry. It never writes `package.json` or the lock, so it cannot repair the drift itself. The teammate either edited the manifest by hand or ran `npm install` and committed only `package.json`. The fix is to run `npm install` locally, which resolves the new dependency and updates `package-lock.json`, then commit both files together. `npm install` is the command that changes dependencies; `npm ci` reproduces them.
code
bash · 5 linesnpm ci # fails: package.json and package-lock.json are not in sync
npm install # resolves chrono-fmt and rewrites package-lock.json
git add package.json package-lock.json
git commit -m "Record chrono-fmt in the lockfile"
npm ci # now passes, and so will the CI jobgo deeper
Recall the one-line difference: npm install changes the tree and the lock, npm ci reproduces the lock exactly and stops when the two files disagree. The fix is a local npm install plus committing the lock.
Explain what npm ci checks: it builds the tree package.json asks for, compares it with the lock, and only then empties node_modules. Read the Missing and Invalid lines to name the drifted dependency.
Treat the failure as the gate working, not a flaky job. Push for package.json and package-lock.json to change together in one commit, and reject pull requests where only one of them moved.
Frame the lock as a reviewed artifact: a pipeline that reproduces it exactly costs a little friction per dependency change and buys installs that never differ between machines.
## What `npm ci` checks before it touches anything `npm ci` is npm's **clean install**, meant for test platforms, continuous integration and deployments. It is not a faster `npm install`; it is a different contract. Before it removes or downloads anything, it works through three steps in order: 1. **Load `package-lock.json`.** With no lockfile it stops at once with a usage error: it "can only install with an existing package-lock.json", and you are told to run an install first. 2. **Build the tree `package.json` asks for** under the current configuration, and compare that tree entry by entry with the one the lock records. 3. **Refuse on any difference.** The headline is "`npm ci` can only install packages when your package.json and package-lock.json are in sync. Please update your lock file with `npm install` before continuing.", followed by one line per mismatch: `Missing: [email protected] from lock file` for a dependency the lock has never heard of, or `Invalid: lock file's [email protected] does not satisfy [email protected]` when a range moved past the locked version. Only when the lock validates does `npm ci` empty the `node_modules` folders (the root's and each workspace's) and install exactly the versions the lock lists. A failed validation therefore leaves the runner's existing folder untouched. ## Why it refuses instead of fixing - **It never writes `package.json` or `package-lock.json`.** npm describes the install as essentially frozen, so there is no code path that could add the missing entry. - **It installs whole projects only.** Individual dependencies cannot be added with `npm ci`; that is what `npm install <name>` is for. - **The mismatch is information.** It means the commit is incomplete: the manifest gained a dependency whose resolved version, tarball URL and integrity hash were never recorded and reviewed. - **A silent repair would hide the problem.** A runner that re-resolved on its own would install whatever version the registry served that minute and write a lock onto a machine that is thrown away after the job. ## `npm install` versus `npm ci` | | `npm install` (no arguments) | `npm ci` | |---|---|---| | Needs a lockfile | No; it creates one | Yes; errors without one | | Lock disagrees with `package.json` | `package.json` wins: npm resolves and updates the lock | Exits with the out-of-sync error | | Writes `package.json` / lock | Yes, by default | Never | | Existing `node_modules` | Reused and updated in place | Emptied after the lock validates | | Add one package | Yes, `npm install chrono-fmt` | No, whole project only | | Where it belongs | A developer machine, when dependencies change | CI, test and deployment | When the lock's versions still satisfy every range, `npm install` uses them exactly, so on an unchanged project both commands produce the same tree. They differ only in what they do when the two files disagree. ## Repairing the drift 1. Check out the branch whose CI run failed. 2. Run `npm install` with no arguments. npm compares `package.json` with the lock, resolves the new dependency within its declared range, and writes the new `packages` entries into `package-lock.json`. 3. Look at the lock diff: the new dependency, plus anything it pulls in, each with a `version`, `resolved` URL and `integrity` hash. 4. Commit `package.json` and `package-lock.json` together. 5. Optionally run `npm ci` locally; it should now pass, and so will CI. If you only need the lock repaired and not a working `node_modules`, `npm install --package-lock-only` updates `package-lock.json` without downloading packages. ## Keeping it from coming back - Make it a review rule: a pull request that changes a dependency section of `package.json` and not `package-lock.json` is incomplete. - Do not "fix" the pipeline by switching it to `npm install`; that removes the check and lets every CI run resolve its own tree. - Do not delete the lock to make the error go away; without a lock every range is resolved from scratch. - If the lock was written with flags that change the shape of the tree, `npm ci` needs those same flags, which is why such settings belong in the committed project `.npmrc`. - Run `npm ci` in pull-request checks, not only on the main branch, so an incomplete commit fails where its author is still looking at it. The out-of-sync error is one of the cheapest failures a pipeline can give you: it names the package, it fires before anything is deleted or downloaded, and the fix is one local command and one commit.
- Why not switch the CI job to `npm install` so it stops failing?Because `npm install` would quietly resolve the missing dependency on the runner, at whatever version the registry serves that day, and write a lock nobody commits. CI would then test a tree no developer has, and the next run could pick a different one. The failure is telling you the commit is incomplete; fix the commit, not the command.
- What does `npm ci` do to an existing `node_modules`, and when?It empties every `node_modules` folder, the root's and each workspace's, and installs from scratch, but only after it has loaded the lock and confirmed that it matches `package.json`. An out-of-sync lock fails the job before anything is removed. That is why `npm ci` is slower on a warm laptop but predictable on a fresh runner.
- Can you update only `package-lock.json`, without downloading into `node_modules`?Yes: `npm install --package-lock-only` resolves against `package.json` and writes the lock without checking or populating `node_modules`. It is handy when you only need a correct lock in the commit; `npm ci` will accept the result as long as the two files agree.
- npm ci updates package-lock.json when it disagrees with package.json.
- Switching the pipeline back to npm install is the right fix for this error.
- npm ci can add a single new package, the same way npm install does.
- npm ci works without a lockfile and simply resolves from package.json.
- Clearing the runner's node_modules makes the out-of-sync error go away.