Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

npm ci fails because package.json and the lockfile disagree

Errornpm error code EUSAGE

Short answer

npm ci refuses to install when the lockfile does not match package.json, or when there is no lockfile. It never repairs it. Run npm install on your own machine, commit the updated package-lock.json, and make sure npm ci uses the same flags the lockfile was created with.

  • Applies to npm 10, Node.js 22, Vite 7, GitHub Actions
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the lines under the error: npm lists exactly which package it found in one file but not the other. Then check that the lockfile is tracked by git.

    git ls-files package-lock.json
    npm ci 2>&1 | head -30
  2. 2Match what you see, then jump to its fix

    1. 1The message says to update the lock file with npm install, and lists packages missing or mismatchedpackage.json was edited without updating the lockfileFix
    2. 2The message says npm ci can only install with an existing package-lock.jsonThere is no package-lock.json in the repositoryFix
    3. 3npm ci fails with dependency errors that npm install did not showThe lockfile was made with different npm flagsFix

What does the error look like?

  • npm error code EUSAGE
  • `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.
  • The `npm ci` command can only install with an existing package-lock.json

Cause 1 of 3

package.json was edited without updating the lockfile

1Check

npm ci exits with an error when the dependencies in the lock do not match package.json; it does not update the lock itself.

git log -3 --oneline -- package.json package-lock.json

2Fix

Run npm install locally to bring the lockfile in line, then commit both files.

npm install
git add package.json package-lock.json
git commit -m "Update lockfile"

3Verify

Run a clean install the way CI does.

npm ci

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

There is no package-lock.json in the repository

1Check

The project must already have a package-lock.json or npm-shrinkwrap.json; a lockfile ignored by git never reaches the server.

git ls-files package-lock.json
git check-ignore -v package-lock.json

2Fix

Generate the lockfile, remove it from .gitignore if it is listed there, and commit it.

npm install
git add package-lock.json
git commit -m "Add lockfile"

3Verify

The file is tracked, and npm ci passes.

git ls-files package-lock.json
npm ci

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The lockfile was made with different npm flags

1Check

If the lock was created with flags such as --legacy-peer-deps or --install-links, npm ci needs the same flags or it is likely to hit errors.

cat .npmrc 2>/dev/null; npm config get legacy-peer-deps

2Fix

Put the flag in the project config so every install uses it, and commit the .npmrc.

npm config set legacy-peer-deps=true --location=project
git add .npmrc

3Verify

Run npm ci again.

npm ci

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Always commit package.json and package-lock.json together.
  • Use npm install to add or change a dependency, and npm ci only to install in CI and deploys.
  • Keep install flags in a committed .npmrc instead of typing them by hand.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.