Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm reports ELIFECYCLE, but the real error is somewhere else

Errornpm ERR! code ELIFECYCLE

Short answer

ELIFECYCLE is not the bug. It means a script that npm ran (build, test, start or an install hook) exited with a non-zero status. The cause is printed above it or in npm's debug log. Re-run the script alone, read the first error, and fix that one.

  • Applies to npm 10 and 11, Node.js 22 and 24, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the failing script by itself and read from the top; the first error is the real one and the lines after it are noise. The command npm printed after the package name is the script that failed.

    npm run build 2>&1 | tee build.log
    node -p "require('./package.json').scripts.build"
  2. 2Match what you see, then jump to its fix

    1. 1Compiler, test or lint errors above the npm lines, then Exit status 1The tool inside the script reported a real errorFix
    2. 2The failure appears during npm install or npm ci, and the named script is install, postinstall or prepareAn install-time script (postinstall, prepare, node-gyp) failedFix
    3. 3The script worked until Node.js was upgraded or switched, and the error mentions a .node file or node-gypA native module was built for another Node.js versionFix

What does the error look like?

  • npm ERR! code ELIFECYCLE
  • npm ERR! errno 1
  • npm ERR! my-app@1.0.0 build: `webpack --mode production`
  • npm ERR! Exit status 1

Cause 1 of 3

The tool inside the script reported a real error

1Check

npm runs the script text through sh and treats any exit code other than 0 as failure. Scripts are often chained with &&, so find which part stopped the chain by running the printed command on its own.

node -p "require('./package.json').scripts.build"
npx tsc --noEmit

2Fix

Fix the error the tool names (type error, failing test, missing file, bad import). Do not hide the exit code: a script that ends in || true or exit 0 turns a real failure into a green build.

npm run build

3Verify

The script ends with exit code 0.

npm run build
echo "exit code: $?"

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

An install-time script (postinstall, prepare, node-gyp) failed

1Check

Install a second time with scripts switched off. If that succeeds, one dependency's build step is the problem, and the debug log names it.

npm install --ignore-scripts
ls -t "$(npm config get cache)/_logs" | head -n 1

2Fix

Read the build output in that log (usually a missing compiler or header, or a Node.js version the package does not support), install what it asks for, then run the skipped steps.

npm rebuild

3Verify

A normal install now finishes without ELIFECYCLE.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

A native module was built for another Node.js version

1Check

Native add-ons are compiled against one Node.js version. After the version changes they must be compiled again. Compare the Node.js version in use with the one you installed with.

node -v
npm -v

2Fix

Rebuild the native add-ons under the Node.js version you run now. If that fails, remove node_modules and install again.

npm rebuild
# or, from a clean state
rm -rf node_modules && npm ci

3Verify

The script that failed runs to the end.

npm run build

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Pin the Node.js version (an .nvmrc or the engines field) so every machine and CI job installs and runs under the same one.
  • Keep script chains short and name each step, so the failing part is obvious from the log.
  • Save the full output of CI builds; npm's own debug log is only on the machine that ran it.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.