npm reports ELIFECYCLE, but the real error is somewhere else
npm ERR! code ELIFECYCLEShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
Compiler, test or lint errors above the npm lines, then Exit status 1The tool inside the script reported a real errorFix - 2
The 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
The 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
- 1
What does the error look like?
npm ERR! code ELIFECYCLEnpm ERR! errno 1npm 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 --noEmit2Fix
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 build3Verify
The script ends with exit code 0.
npm run build
echo "exit code: $?"Confirmed by docs.npmjs.com
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 12Fix
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 rebuild3Verify
A normal install now finishes without ELIFECYCLE.
npm installConfirmed by docs.npmjs.com
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 -v2Fix
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 ci3Verify
The script that failed runs to the end.
npm run buildConfirmed by docs.npmjs.com
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
Back end
npm start says the script is missing
npm error Missing script: "start"
npm start runs the start script from the nearest package.json.
4 causes, each with a fixBack end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fix