npm's EUSAGE code means a command was invoked incorrectly — wrong flags, missing arguments, or, most commonly, an `npm ci` run where package.json and package-lock.json are out of sync.
`EUSAGE` is npm's generic "usage error" exit code. npm prints it whenever a command is invoked in a way it cannot accept: an unknown or misspelled flag, a missing required argument, an invalid value passed to an option, or a subcommand whose preconditions are not met. In other words, it is the same class of error you would get from a CLI printing its usage/help text and exiting non-zero — not a failure inside your application code. By far the most common place developers hit EUSAGE in real builds is `npm ci`. `npm ci` is designed for reproducible installs and refuses to run unless a `package-lock.json` (or `npm-shrinkwrap.json`) exists and is in sync with `package.json`. If the lock file is missing, or its dependency set no longer matches `package.json`, npm treats this as incorrect usage of the command and exits with EUSAGE, printing a message like "`npm ci` can only install packages when your package.json and package-lock.json ... are in sync." Because `npm ci` is the standard install command in CI/CD and Docker builds, this is where most people first encounter the code — but the same EUSAGE code appears for any mis-invoked npm command (for example `npm install --unknown-flag` or running a subcommand without its required argument).
EUSAGE is a usage error, so npm almost always tells you exactly what it rejected. Run the failing command again and read the lines after npm ERR! Usage error — npm prints the offending command's usage/help text.
# Re-run and capture the full output
npm ci 2>&1 | head -n 40If the message mentions an unknown option or a missing argument, fix the command itself (see step 4). If it says package.json and package-lock.json are not in sync, continue with steps 2 and 3 — that is the lock-file case.
npm ci requires a lock file and will EUSAGE without one. Make sure package-lock.json (or npm-shrinkwrap.json) is present and not excluded from version control or your Docker build context.
# Is the lock file present?
ls -l package-lock.json
# Is it tracked by git (not gitignored)?
git ls-files --error-unmatch package-lock.jsonIf the lock file is missing, generate one with npm install, then commit it. If it is being excluded, remove package-lock.json from .gitignore / .dockerignore and commit it.
When the lock file is out of sync, regenerate it locally so it matches package.json and your npm version, then commit the result. The removals below are scoped to your project directory only.
# Remove the lock file and installed modules (project-local only)
rm -rf package-lock.json node_modules
# Reinstall to produce a fresh, in-sync lock file
npm install
# Commit the regenerated lock file
git add package-lock.json
git commit -m "chore: resync package-lock.json"On Windows PowerShell: Remove-Item -Recurse -Force package-lock.json, node_modules.
After committing, re-run npm ci to confirm it now passes.
If the error was not about the lock file, npm rejected the command's flags or arguments. Compare what you ran against the built-in help.
# Show valid usage for the command that failed
npm <command> --help # e.g. npm install --helpCommon fixes:
- Remove or correct an unknown/misspelled flag (--save-dev, not --savedev).
- Supply a required argument (e.g. npm uninstall <package> needs a package name).
- Replace deprecated flags reported in the output with their current equivalents.
In package.json scripts, double-check the npm subcommands invoked there too — a typo in a script is a frequent source of EUSAGE in CI.
A lock file written by one npm major version can fail to validate under another, producing EUSAGE during npm ci. Make local and CI use the same npm.
# Check what you have locally
node --version
npm --version
# Inspect the lock file format your repo committed
npm pkg get # sanity-check package.json is readable
head -n 5 package-lock.json # shows "lockfileVersion"For reference: npm 5/6 write lockfileVersion: 1, npm 7+ write lockfileVersion: 2, and npm 9+ write lockfileVersion: 3. Pick one npm version and use it everywhere. Pin it in CI (for example actions/setup-node with a fixed node-version, or a fixed Node base image in Docker), and update npm only deliberately:
# Update to the latest npm if you intend to bump the lockfile format
npm install -g npm@latestIf you bump npm, regenerate and commit package-lock.json (step 3) so the committed format matches what CI runs.
EUSAGE is a generic code, so the fix always depends on the specific command in the error output — do not assume it is a lock-file problem until npm says so. For npm workspaces (monorepos), npm ci validates the entire workspace tree, so an out-of-sync lock entry in any member package can fail the whole install; regenerate the lock file from the repo root. In Docker, the classic case is a package-lock.json excluded by .dockerignore while the image runs npm ci — copy both package.json and package-lock.json before running the install. If you only need a non-strict install (for example during early development), npm install updates the lock file in place and does not enforce the sync check, whereas npm ci is intentionally strict and reproducible; prefer keeping npm ci in CI and fixing the lock file rather than switching CI to npm install.
npm notice access token expired or revoked. Please try logging in again.
Token has expired - npm authentication failure
npm ERR! code EAI_AGAIN
How to fix "EAI_AGAIN" in npm
npm error code E403 npm error 403 Forbidden - PUT https://registry.npmjs.org/<package>
How to fix 'E403 Forbidden' error in npm
npm ERR! code E401 npm ERR! 401 Unauthorized
How to fix "E401 Unauthorized" in npm
npm ERR! DEPTH_ZERO_SELF_SIGNED_CERT
How to fix "DEPTH_ZERO_SELF_SIGNED_CERT" in npm