npm audit --audit-level: Gate on Severity
npm audit --audit-level=<sev> makes npm audit exit non-zero only when a vulnerability at or above that severity exists, so low-severity noise does not fail the build.
Plain npm audit exits non-zero on any vulnerability, which is too aggressive for most pipelines. --audit-level raises the bar to high or critical so the gate is actionable.
What it does
npm audit checks the installed dependency tree against the npm advisory database. By default any finding makes it exit 1. --audit-level=high (or critical) means it only exits non-zero when a finding meets that severity; lower findings still print but do not fail.
Common usage
# fail only on high or critical
npm audit --audit-level=high
# ignore devDependencies, gate on prod tree only
npm audit --omit=dev --audit-level=high
# machine-readable for a report
npm audit --json --audit-level=criticalOptions
| Flag | What it does |
|---|---|
| --audit-level <sev> | info, low, moderate, high, critical gate |
| --omit=dev | Exclude devDependencies (replaces --production) |
| --production | Legacy alias for excluding dev deps (npm 6) |
| --json | Machine-readable output |
| --registry <url> | Audit against a specific registry |
In CI
npm audit needs a resolved tree, so run npm ci first. Use --audit-level=high --omit=dev so the gate ignores dev-only and low-severity issues that you cannot act on. Note npm audit makes a network call to the registry advisory endpoint, so an offline runner will error.
Common errors in CI
"npm ERR! audit endpoint returned an error" or a 503 means the registry advisory service was unreachable or rate-limited; retry or set a registry. "This command requires an existing lockfile" means there is no package-lock.json; run npm i or commit the lockfile. A job failing on low-severity transitive issues just needs --audit-level raised.