npm "ERR! code ELIFECYCLE" in CI: how to surface the real error

TL;DR

ELIFECYCLE is npm's generic "a script exited non-zero" wrapper; the real error is in the script's own output above it. In CI the cause is usually visible a few dozen lines up: a test failure, a build error, or a missing environment variable. Scroll up before theorizing, capture the script's stderr separately, and run the script with verbose output when the logs are truncated.

The query

npm "ERR! code ELIFECYCLE" in CI: how to surface the real error

Use this when

• CI fails with ELIFECYCLE and no clear cause
• The underlying script error is buried in logs
• Local npm runs pass but CI fails
• Scripts fail silently in CI

Not for when

• npm install or registry errors (different codes)
• Dependency resolution failures
• Auth errors

Steps

Step 1: Read above the ELIFECYCLE line

The actual error precedes the ELIFECYCLE summary, often by many lines. Expand the full log and search upward from the failure for the first error-looking output: that is the real failure. Expected output: the underlying script error identified.

Step 2: Run the script directly with verbose output

Reproduce by running the failing script (not through npm) with maximum verbosity. Direct execution shows errors npm's wrapper obscures, and lets you see exit codes and stderr cleanly. Expected output: the unmasked error from the script itself.

Step 3: Compare environments: local vs CI

Diff the environments: Node version, environment variables, available memory, working directory. CI-specific failures are usually a missing env var or a version difference, both invisible in the ELIFECYCLE line. Expected output: the environmental difference named.

Step 4: Capture script output to a file

Redirect the script's full output to a log file as a CI artifact. Truncated console logs hide the cause; a complete artifact preserves it for every future failure. Expected output: complete logs available for every failed run.

Step 5: Make scripts fail loudly

Ensure scripts exit non-zero with a clear message on failure, and set CI to treat warnings as errors where appropriate. A script that fails quietly produces ELIFECYCLE mysteries; a script that fails loudly produces answers. Expected output: future failures self-diagnosing from the log tail.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstEEE6-vhxwpeDxQnR1mapQ