How to fix npm ERR! gyp ERR! build error npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2 in npm

npmINTERMEDIATEHIGHUpdated Dec 3, 2025· 112 views

This error occurs when npm tries to install a package with native C++ code but the build process fails, usually due to missing build tools, Python configuration issues, or version incompatibilities. The `make` command failing with exit code 2 typically indicates missing dependencies or compilation errors.

Quick fix

Fixes gyp ERR!

npm install --verbose 2>&1 | tee build.log
  1. Read the full error output carefully
  2. Clear npm cache and node_modules
  3. Install platform-specific build tools
  4. Verify Python is installed and configured
npm — error
npm install --verbose 2>&1 | tee build.log
npm ERR! gyp ERR! build error
npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2
shell
npm install --verbose 2>&1 | tee build.log

What this error means

When npm installs packages containing native C++ code, it uses node-gyp to compile these modules. The error 'make failed with exit code 2' means the build command encountered an unrecoverable error during compilation. This is not an npm issue itself, but rather a problem in the build environment—missing compilers, Python, build tools, or incompatible versions.

Typical symptoms

  • npm install fails during package installation with gyp build error
  • Installation works on some machines but fails on others
  • Error appears when installing packages with native bindings like node-sass, bcrypt, or sqlite3
  • The error message is preceded by compilation errors or missing tool messages
  • CI/CD pipelines fail at the npm install step

Common causes

  1. Missing or outdated build tools (make, g++, clang) on your system
  2. Python not installed or not configured correctly (node-gyp requires Python)
  3. Incompatible versions of Node.js and node-gyp
  4. Corrupted node_modules or package-lock.json file
  5. Missing Visual C++ Build Tools on Windows
  6. Xcode Command Line Tools not installed on macOS
  7. Using deprecated packages like node-sass instead of modern alternatives

How to fix "npm ERR! gyp ERR! build error npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2"

1Read the full error output carefully

The most important step is to look at the error messages ABOVE the 'make failed' line. The actual error is usually printed first.

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

Search the log for the first error message.

2Clear npm cache and node_modules

Start with a clean slate:

macOS/Linux:

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

Windows:

powershell
rd /s /q "node_modules"
del package-lock.json
npm cache clean --force
npm install
3Install platform-specific build tools

Node-gyp requires a C/C++ compiler.

Windows (PowerShell as Administrator):

bash
npm install --global --production windows-build-tools

macOS:

bash
xcode-select --install

Linux (Ubuntu/Debian):

bash
sudo apt-get update
sudo apt-get install build-essential python3 make g++
4Verify Python is installed and configured

Node-gyp requires Python. Verify it's installed:

bash
python3 --version

Configure npm to use it:

bash
npm config set python /usr/bin/python3
5Update npm and node-gyp

Update to fix compatibility issues:

bash
npm install -g npm@latest
npm install -g node-gyp@latest
6Check for deprecated packages and use alternatives

Some packages are known to cause gyp errors:

If using node-sass:

bash
npm uninstall node-sass
npm install sass --save-dev

If using bcrypt:

bash
npm uninstall bcrypt
npm install bcryptjs --save

These alternatives don't require compilation.

Advanced notes

Exit code 2 from make is generic; the actual error is always printed above it. Common hidden errors include missing Python, missing node headers, or compilation warnings treated as errors. On CI/CD systems, install build tools in the pipeline BEFORE npm install. Some packages offer environment variables to skip native build—check the package README.

Frequently asked questions

What does "gyp ERR!" mean?
When npm installs packages containing native C++ code, it uses node-gyp to compile these modules. The error 'make failed with exit code 2' means the build command encountered an unrecoverable error during compilation. This is not an npm issue itself, but rather a problem in the build environment—missing compilers, Python, build tools, or incompatible versions.
How do I fix "gyp ERR!"?
This error occurs when npm tries to install a package with native C++ code but the build process fails, usually due to missing build tools, Python configuration issues, or version incompatibilities. The make command failing with exit code 2 typically indicates missing dependencies or compilation errors.
What causes "gyp ERR!"?
Missing or outdated build tools (make, g++, clang) on your system Python not installed or not configured correctly (node-gyp requires Python) Incompatible versions of Node.js and node-gyp
Is the "gyp ERR!" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading