Fix: npm ERR! code ELIFECYCLE (errno 1, Failed at script)

The Error

You run npm run build, npm install, or npm test and get:

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! my-app@1.0.0 build: `react-scripts build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the my-app@1.0.0 build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

The key line is: “This is probably not a problem with npm.” npm is telling you that the script it tried to run exited with an error. ELIFECYCLE is just the wrapper. The real error is somewhere above this block in your terminal output.

You might also see variations like:

npm ERR! code ELIFECYCLE
npm ERR! errno 2

npm ERR! code ELIFECYCLE
npm ERR! errno 137

The errno tells you how the process exited. 1 is a generic failure. 2 usually means misuse of a shell command. 137 means the process was killed (out of memory). Each one points to a different root cause.

Why This Happens

ELIFECYCLE means an npm lifecycle script (like build, start, test, postinstall, or prepare) exited with a non-zero status code. npm ran a command, that command failed, and npm reported the failure.

The error is never about npm itself. It is always about what the script tried to do. The most common underlying causes:

• Your build or start script has a code error. A syntax error, a missing import, a failed compilation. The real error message is printed above the ELIFECYCLE block.
• node_modules is corrupted. A previous install was interrupted, a package was partially downloaded, or your lockfile is out of sync.
• node-gyp can’t compile a native module. A package with C/C++ bindings (like bcrypt, sharp, node-sass, sqlite3) failed to build because system dependencies are missing.
• Wrong Node.js version. The package requires a specific Node.js version range and yours is outside it.
• The build ran out of memory. Large projects (especially those using Webpack or TypeScript) can exceed Node.js’s default memory limit.
• A postinstall or prepare script in a dependency failed. Some packages run build steps after installation.
• Windows-specific issues. Path length limits, missing build tools, or shell incompatibilities.

Fix 1: Read the Actual Error Above ELIFECYCLE

This is the most important step and the one most people skip. Scroll up in your terminal. The real error is above the npm ERR! lines.

For example, you might see:

Module not found: Can't resolve './components/Header'

SyntaxError: Unexpected token '}'

error TS2307: Cannot find module '@/utils/helpers'

gyp ERR! build error

Each of these has a completely different fix. The ELIFECYCLE block is just npm saying “the script failed.” Your job is to find and fix the error the script reported.

If your terminal doesn’t show enough history, run the command again and pipe to a file:

npm run build 2>&1 | tee build-output.log

Then search the log for the first error. If the error is about a missing module, see Fix: Error Cannot find module or Fix: Module not found: Can’t resolve.

Fix 2: Delete node_modules and Reinstall

Corrupted node_modules is behind a huge number of ELIFECYCLE failures. A broken install, an interrupted npm install, switching branches with different dependencies, or even a corrupted npm cache can all leave node_modules in a bad state.

Clean reinstall:

rm -rf node_modules package-lock.json
npm install

On Windows (Command Prompt):

rmdir /s /q node_modules
del package-lock.json
npm install

On Windows (PowerShell):

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Deleting package-lock.json forces npm to resolve the entire dependency tree from scratch. If you need to preserve exact versions from your lockfile (e.g., in CI), delete only node_modules:

rm -rf node_modules
npm ci

npm ci is designed for clean installs. It deletes node_modules automatically and installs exactly what the lockfile specifies. It is faster than npm install and more reliable in CI environments.

If npm install itself fails with dependency conflicts, see Fix: npm ERR! ERESOLVE unable to resolve dependency tree.

Fix 3: Fix node-gyp Build Failures

If the error output contains gyp ERR!, a native module failed to compile. node-gyp compiles C/C++ addons and requires build tools to be installed on your system.

The error typically looks like:

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! not ok
npm ERR! code ELIFECYCLE

On macOS

Install Xcode Command Line Tools:

xcode-select --install

On Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y build-essential python3

On Windows

Windows requires the most setup. Install the build tools:

npm install -g windows-build-tools

Or install them manually:

1. Install Visual Studio Build Tools with the “Desktop development with C++” workload.
2. Install Python 3.x from python.org.
3. Tell npm where to find Python:

npm config set python python3

If you’re using node-gyp v10+, Python 3.12+ is supported. Older versions of node-gyp may need Python 3.6-3.11.

After installing the build tools, rebuild:

npm rebuild

Or do a clean install:

rm -rf node_modules package-lock.json
npm install

Common native module alternatives

Some native modules have pure JavaScript alternatives that don’t require compilation:

If you’re hitting node-gyp errors with node-sass, switch to sass. node-sass is deprecated and consistently causes build problems:

npm uninstall node-sass
npm install sass

No code changes needed in most cases. Sass-loader and framework CLIs automatically use whichever Sass compiler is installed.

Fix 4: Use the Correct Node.js Version

Some packages require a specific Node.js version range. If you’re on the wrong version, builds can fail with cryptic errors that end in ELIFECYCLE.

Check what your project expects:

cat package.json | grep -A 2 '"engines"'

You might see:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Check your current version:

node -v

If there is a mismatch, switch using nvm:

nvm install 18
nvm use 18

Or with fnm:

fnm install 18
fnm use 18

If the project has an .nvmrc or .node-version file:

nvm use

After switching Node.js versions, always reinstall your dependencies. Native modules are compiled against a specific Node.js ABI, and they will not work across versions:

rm -rf node_modules package-lock.json
npm install

Fix 5: Increase Node.js Memory Limit

If the error output includes FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed or JavaScript heap out of memory, or if the errno is 137 (OOM killed), the build is running out of memory.

Node.js defaults to roughly 1.5 GB of heap memory. Large projects with big dependency trees, many source files, or complex Webpack/TypeScript compilations can exceed this.

Increase the limit:

export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

On Windows (Command Prompt):

set NODE_OPTIONS=--max-old-space-size=4096
npm run build

On Windows (PowerShell):

$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

You can also set it directly in your package.json script:

{
  "scripts": {
    "build": "node --max-old-space-size=4096 ./node_modules/.bin/react-scripts build"
  }
}

Or using the cross-platform cross-env package:

npm install --save-dev cross-env

{
  "scripts": {
    "build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 react-scripts build"
  }
}

Common memory limit values:

• 4096 — 4 GB (handles most projects)
• 8192 — 8 GB (for very large monorepos or heavy TypeScript projects)

If even 8 GB is not enough, the problem is usually not memory. Look for circular dependencies, massive bundle sizes, or misconfigured build tools.

For a deeper look at memory issues in JVM-based tooling, see Fix: java.lang.OutOfMemoryError: Java heap space.

Fix 6: Fix postinstall and prepare Script Failures

Sometimes ELIFECYCLE happens during npm install itself, not during npm run build. This means a package’s postinstall, prepare, or install lifecycle script failed.

The error looks like:

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! some-package@2.1.0 postinstall: `node scripts/build.js`
npm ERR! Exit status 1

Look at the package name in the error. It is not your project — it is a dependency that runs a build step after being installed.

Common fixes:

Skip optional dependencies that have postinstall scripts:

npm install --ignore-scripts

This skips all lifecycle scripts. Use it to get past the install, then manually run your project’s prepare/build steps. Be aware that some packages genuinely need their postinstall scripts (e.g., esbuild, sharp, puppeteer).

Install the specific package separately with more info:

npm install some-package --verbose

The verbose output will show exactly what the postinstall script tried to do and where it failed.

Skip scripts only for a specific package:

If you need most postinstall scripts to run but want to skip one, add it to your .npmrc:

ignore-scripts=false

Then override per-package in package.json:

{
  "scripts": {
    "preinstall": "npx only-allow npm"
  }
}

Or rebuild just the failing package after install:

npm install --ignore-scripts
npm rebuild some-package

Fix 7: Fix .npmrc and Configuration Issues

A misconfigured .npmrc can cause ELIFECYCLE errors. npm reads configuration from multiple locations, and conflicting settings can break installs.

Check your active configuration:

npm config list

This shows merged settings from all .npmrc files (project, user, and global). Look for anything unexpected, especially:

• script-shell — Overrides the shell used to run scripts. If it points to a shell that doesn’t exist, every script will fail.
• prefix — Changes where global packages are installed. A wrong prefix can cause path issues.
• registry — Points to a custom registry. If the registry is down or unrequested auth is needed, installs fail.

Check for project-level .npmrc:

cat .npmrc

Check for user-level .npmrc:

cat ~/.npmrc

If you suspect .npmrc is the problem, temporarily rename it and try again:

mv .npmrc .npmrc.bak
npm install

Fix 8: Fix Lock File Conflicts

If you recently merged branches or pulled changes, your package-lock.json might have merge conflicts or stale entries. This can cause npm install to produce a broken node_modules, which then causes ELIFECYCLE when running scripts.

Signs of a lock file problem:

• npm install succeeds but npm run build fails with missing modules
• Git shows merge conflict markers (<<<<<<<) in package-lock.json
• Different team members get different results from npm install

Fix:

rm package-lock.json
rm -rf node_modules
npm install

This regenerates the lock file from your package.json. Commit the new package-lock.json:

git add package-lock.json
git commit -m "Regenerate package-lock.json"

If you are using a .npmrc that sets package-lock=false, npm will not create a lock file at all. In that case, dependency resolution can vary between installs, which makes ELIFECYCLE errors less reproducible.

Fix 9: Windows-Specific Issues

Windows causes more ELIFECYCLE errors than macOS or Linux. Here are the Windows-specific problems and their fixes.

Path length limit

Windows has a 260-character path limit by default. Deeply nested node_modules directories can exceed it. npm 3+ uses a flat node_modules structure to mitigate this, but some packages still create deep nesting.

Enable long paths (requires admin privileges):

# Run PowerShell as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Or enable it through Group Policy: Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths.

Shell issues

npm uses cmd.exe by default on Windows to run scripts. Some scripts use Unix shell syntax (like &&, rm -rf, export) that does not work in cmd.exe.

Switch npm to use Git Bash:

npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"

Or use WSL (Windows Subsystem for Linux) to run your project in a Linux environment entirely.

node-gyp and Visual Studio

node-gyp on Windows requires:

1. Visual Studio Build Tools (or full Visual Studio) with the “Desktop development with C++” workload
2. Python 3.x

The most reliable way to install both:

npm install -g windows-build-tools

This may require an elevated (Administrator) terminal. If it stalls, install Python and Visual Studio Build Tools manually.

Still Not Working?

Clear the npm cache

A corrupted npm cache can cause packages to install incorrectly, leading to ELIFECYCLE at runtime:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Check for global and local version conflicts

If you have a package installed both globally and locally, the wrong version might run:

npm ls -g --depth=0

Compare with your local versions. If in doubt, remove the global install:

npm uninstall -g some-package

Run the failing script directly

Skip npm and run the command yourself to see unfiltered output:

# If your build script is "react-scripts build"
npx react-scripts build

This sometimes surfaces errors that npm’s logging truncates.

Check for antivirus or permissions interference

On Windows, antivirus software (especially Windows Defender) can lock files in node_modules during install, causing partial writes and subsequent ELIFECYCLE failures. Try adding your project directory to your antivirus exclusion list.

On Linux/macOS, permission issues can cause the same. If node_modules was created with sudo, you may not be able to modify it. Fix ownership:

sudo chown -R $(whoami) node_modules

Better yet, never use sudo with npm.

Use npm install --verbose

If you still can’t find the root cause, reinstall with verbose logging:

npm install --verbose 2>&1 | tee install-log.txt

The verbose output shows every HTTP request, file operation, and script execution. Search the log for the first error or warning.

Upgrade npm

Older versions of npm have bugs that cause spurious ELIFECYCLE errors. Update to the latest:

npm install -g npm@latest

Then clean install:

rm -rf node_modules package-lock.json
npm install

Try a different package manager

If npm keeps giving you problems, try pnpm or Yarn. They handle dependency resolution and script execution differently and sometimes avoid issues that npm hits:

npx pnpm install
pnpm run build

Related: If npm install fails due to dependency conflicts, see Fix: npm ERR! ERESOLVE unable to resolve dependency tree. If npm can’t find the script you’re trying to run, see Fix: npm ERR! Missing script: “start”.