npm ERR! code ELIFECYCLE / script failed (exit status 1)
npm printed ELIFECYCLE and exit status 1. That almost never means npm is broken — it means the script npm was asked to run exited non-zero. Scroll up for the real error.
What ELIFECYCLE actually means
npm ERR! code ELIFECYCLE is npm’s wrapper message: “I ran a lifecycle script and it returned a non-zero exit code.” The useful line is almost always higher in the log — a Jest failure, tsc error, webpack module-not-found, Python/node-gyp compile failure, or a shell command not found.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build: `vite build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] build script.That block only names which script failed. The real cause is the Vite/webpack/tsc output printed before it.
Cause table
| What you see above ELIFECYCLE | Likely cause | What to do |
|---|---|---|
| Test assertion / Jest / Vitest / Mocha fail | npm test / prepublishOnly runs tests | Fix or skip the failing test; run npm test -- --verbose |
| TypeScript / ESLint / webpack / Vite error | Build script is strict | Fix the first compiler error; don’t chase the ELIFECYCLE line |
node-gyp / Python / MSBuild fail in postinstall | Native addon compile | Install build tools; pin Node; see peer/engine warnings |
| husky / lint-staged / pre-commit | Git hook ran npm test or lint | Run the hook command alone; HUSKY=0 only as a temporary escape |
sh: vite: not found / command not found | Binary missing from PATH / incomplete install | rm -rf node_modules && npm ci; see ENOENT |
| Peer dependency / ERESOLVE noise then script fail | Wrong major of React etc. | npm ERESOLVE; align versions |
| Works locally, fails in CI | Different Node, missing env, case-sensitive FS, no TTY | Match engines; print node -v; check env vars CI injects |
| Works on Mac, fails on Windows (or reverse) | Shell scripts, path separators, line endings, NODE_OPTIONS | Use cross-env / npm-run-all; avoid bash-only one-liners in scripts |
Find the real error
- Scroll to the first red/error line above the ELIFECYCLE banner — that is the bug.
- Open
package.json→scriptsand copy the exact command for the failing name (build,test,prepare, …). - Run that command directly (not via a parent script):
npx vite build,npx tsc -p .,npx jest. Cleaner stack traces. - If the failure is during
npm install, checkpreinstall/install/postinstall/prepare— those run automatically.
# See what npm will run
npm run build --loglevel verbose
# Or execute the script body yourself
node ./node_modules/typescript/bin/tsc -p tsconfig.jsonPaste a mysterious error blob into What is this?. Diff two package.json / lockfiles in the text diff tool when CI and laptop disagree.
Lifecycle scripts people forget
- prepare / prepublishOnly — run on install from git and before publish; often run the full test/build suite.
- postinstall — patch-package, husky install, native builds. A failure here aborts
npm installwith ELIFECYCLE. - pre/post hooks —
prebuildruns beforebuild. A silent failure inpre*still surfaces as ELIFECYCLE on the parent name.
CI vs local checklist
- Same Node major (
enginesfield +.nvmrc/ Volta / asdf). - Prefer
npm ciin CI (lockfile-strict) overnpm install. - Export required env vars; never assume a developer’s
.envis present. - Linux CI is case-sensitive —
import './Button'vsbutton.tsxbites after a Mac-only life. - Out-of-memory kills look different: exit 137 / heap OOM, not always a neat ELIFECYCLE — see JavaScript heap out of memory and exit code 137.
Related
npm ERR! code ENOENT · npm ERESOLVE · Cannot use import statement outside a module · JavaScript heap out of memory · Node OpenSSL envelope error · JSON formatter
Questions
What does npm ERR! code ELIFECYCLE mean?
A package.json script (build, test, postinstall, prepare, …) exited with a non-zero status. npm is reporting the failure; the real error is printed above that banner.
How do I find the actual error?
Scroll above the ELIFECYCLE lines for the first compiler, test, or shell error. Re-run the script command directly for a cleaner log.
Why does npm install fail with ELIFECYCLE?
Usually a failing postinstall / prepare / husky install or a native addon build (node-gyp), not the registry download itself.
Is ELIFECYCLE the same as ENOENT or ERESOLVE?
No. ENOENT is a missing file/path; ERESOLVE is a peer-dependency tree conflict. ELIFECYCLE is “the script ran and failed.”
Why does it pass locally but fail in CI?
Different Node version, missing env vars, case-sensitive paths, or CI running extra lifecycle scripts (test/lint) that you skip locally.
Can I ignore ELIFECYCLE?
Only by fixing or intentionally changing the script. Forcing with --ignore-scripts hides postinstall bugs and is rarely safe for apps.
Published .