How to fix npm ERR! code EUSAGE npm ERR! Usage error in npm

npmBEGINNERMEDIUMUpdated May 28, 2026· 363 views

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.

Quick fix

Fixes npm ERR! code EUSAGE npm ERR! Usage error

# Re-run and capture the full output
npm ci 2>&1 | head -n 40
  1. Read the full error message to identify the bad command
  2. Confirm package-lock.json exists and is committed
  3. Resync package-lock.json with package.json
  4. Fix the command syntax for non-lockfile usage errors
npm — error
# Re-run and capture the full output
npm ci 2>&1 | head -n 40
npm ERR! code EUSAGE
npm ERR! Usage error

What this error means

`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).

Typical symptoms

  • A command fails immediately with `npm ERR! code EUSAGE` and `npm ERR! Usage error`, often followed by the command's usage/help text
  • `npm ci` aborts with a message that package.json and package-lock.json are out of sync
  • Build pipeline fails during the dependency-installation step in CI/CD or Docker
  • `npm install` succeeds locally but `npm ci` fails in the build environment
  • npm prints the usage/help block for the command you ran instead of executing it (typo'd flag or missing argument)

Common causes

  1. Running `npm ci` when package-lock.json is missing, or when it is out of sync with package.json (the most common cause)
  2. An unknown, misspelled, or deprecated command-line flag passed to an npm command (e.g. `--unknown-flag`)
  3. A required argument is missing or an option was given an invalid value (e.g. a subcommand that needs a package name)
  4. package.json or package-lock.json edited by hand, or regenerated by a different npm major version, leaving the two out of sync
  5. package-lock.json was committed from an old npm that wrote lockfileVersion 1, while the build runs a newer npm (npm 7+ writes lockfileVersion 2/3) — a mismatch that surfaces during `npm ci`

How to fix "npm ERR! code EUSAGE npm ERR! Usage error"

1Read the full error message to identify the bad command

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.

bash
# Re-run and capture the full output
npm ci 2>&1 | head -n 40

If 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.

2Confirm package-lock.json exists and is committed

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.

bash
# Is the lock file present?
ls -l package-lock.json

# Is it tracked by git (not gitignored)?
git ls-files --error-unmatch package-lock.json

If 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.

3Resync package-lock.json with package.json

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.

bash
# 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.

4Fix the command syntax for non-lockfile usage errors

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.

bash
# Show valid usage for the command that failed
npm <command> --help   # e.g. npm install --help

Common 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.

5Align npm and Node.js versions between local and 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.

bash
# 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:

bash
# Update to the latest npm if you intend to bump the lockfile format
npm install -g npm@latest

If you bump npm, regenerate and commit package-lock.json (step 3) so the committed format matches what CI runs.

Advanced notes

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.

Frequently asked questions

What does "npm ERR! code EUSAGE npm ERR! Usage error" mean?
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.
How do I fix "npm ERR! code EUSAGE npm ERR! Usage error"?
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.
What causes "npm ERR! code EUSAGE npm ERR! Usage error"?
Running npm ci when package-lock.json is missing, or when it is out of sync with package.json (the most common cause) An unknown, misspelled, or deprecated command-line flag passed to an npm command (e.g. --unknown-flag) A required argument is missing or an option was given an invalid value (e.g. a subcommand that needs a package name)
Is the "npm ERR! code EUSAGE npm ERR! Usage error" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading