npm ERR! code ELIFECYCLE — The Script Failed, npm Is Just the Messenger

ELIFECYCLE means a package.json lifecycle script (build, test, start...) exited non-zero. The useful error is above the npm banner — treat npm as a wrapper, not the cause.

What you'll see

Root causes

The underlying script genuinely failed

TypeScript compile errors, failing tests, missing env vars — npm re-reports the exit code. Scroll above the npm block for the real stack/trace.

Environment drift between machines

Node version differences, node_modules out of sync, missing .env. Try: rm -rf node_modules package-lock.json && npm install — the classic reset.

Script defined with wrong path/flags

package.json 'build': 'tsnd build.ts' where the file moved, or a Windows/Linux shell mismatch (npm scripts run through sh on Unix).

Fix it

  1. Run the failing script directly to see the real error
    npm run build --silent   # or copy the command from package.json and run it yourself
  2. Reset dependencies if the error is missing-module shaped
    rm -rf node_modules && npm ci   # npm ci honors the lockfile exactly; falls back to npm install if no lockfile
  3. Pin the toolchain where CI differs
    # engines: { "node": ">=20 <21" } in package.json + node -v; or use nvm/volta to match versions
  4. For tests: run a single failing file first
    npx jest path/to/failing.test.ts   # narrow before re-running the whole suite

Field note

npm ERR! at the bottom is noise; the tool's own error (tsc, jest, vite...) is the signal. In CI, echo the node/npm versions in the job — most 'works locally' ELIFECYCLE failures are version drift.

Common questions

What exit code should I read from ELIFECYCLE?

The message includes it (Exit status 1/2...). It's whatever your script returned — npm adds no failure of its own. 1 is usually the tool's generic failure; 2 in some tools means argument errors.

Why does npm ci fix things npm install doesn't?

npm ci deletes node_modules and installs exactly from the lockfile, removing the tree drift that a series of npm installs can accumulate.

Related fixes

Ship it right the first time

Our most-documented failures, packaged as ready-to-ship starter kits: Docker, Kubernetes, and Terraform.

Browse the template store →

One-time. Yours to modify. Instant download from the NinjaOps template store.