npm ci fails because package.json and the lockfile disagree
npm error code EUSAGEShort 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.
Fix it fast
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 -302Match what you see, then jump to its fix
- 1
The message says to update the lock file with npm install, and lists packages missing or mismatchedpackage.json was edited without updating the lockfileFix - 2
The message says npm ci can only install with an existing package-lock.jsonThere is no package-lock.json in the repositoryFix - 3
npm ci fails with dependency errors that npm install did not showThe lockfile was made with different npm flagsFix
- 1
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.json2Fix
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 ciConfirmed by docs.npmjs.com
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.json2Fix
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 ciConfirmed by docs.npmjs.com
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-deps2Fix
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 .npmrc3Verify
Run npm ci again.
npm ciConfirmed by docs.npmjs.com
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 fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix