Victor's room

Overview & Root Cause Summary: The error gyp ERR! build error / gyp ERR! stack Error: `make` failed with exit code: 2 / npm ERR! command sh -c node-gyp rebuild occurs during npm install when a package containing native C/C++ bindings (such as node-sass, bcrypt, sqlite3, or canvas) attempts to compile from source code. The compilation fails due to missing C/C++ build tools and Python headers, deprecated native modules incompatible with newer Node.js V8 engine ABIs, or missing underlying system C libraries.

Understanding the Root Causes

• Missing C/C++ Toolchain & Python 3: node-gyp requires an active Python 3 runtime and platform C/C++ compilers (GCC/G++ on Linux, Xcode CLI tools on macOS, or MSVC on Windows) to orchestrate native compilation.
• Node.js Engine ABI Incompatibilities: Installing unmaintained native packages (such as legacy node-sass) on modern Node.js runtimes (Node 18, 20, or 22) where internal V8 engine C++ API signatures have changed.
• Missing System-Level Development Headers: Specific native modules require external shared C libraries (e.g., canvas requires libcairo2-dev and libpango1.0-dev; sqlite3 requires C SQLite headers).
• Python Path Misconfiguration: node-gyp attempting to locate legacy Python 2 or targeting an unrecognized Python binary path in multi-version environments.

Step 1: Quick Fix (Install OS Build Toolchains and Python)

Equip your operating system with the standard C/C++ compiler suite and development libraries required by node-gyp.

# On Debian / Ubuntu:
sudo apt-get update
sudo apt-get install -y build-essential python3 python3-dev make g++

# On Fedora / RHEL / Rocky Linux:
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y python3 python3-devel

# On macOS (Install Xcode Command Line Tools):
xcode-select --install

# Explicitly configure npm to use your Python 3 binary path:
npm config set python $(which python3)

Step 2: Replace Deprecated Native Addons with Modern Alternatives

Many node-gyp failures occur because outdated libraries are fundamentally incompatible with modern Node.js versions. Migrate to active pure JavaScript or WebAssembly replacements.

# Scenario A: Replace deprecated node-sass with modern Dart Sass:
npm uninstall node-sass
npm install -D sass

# Scenario B: Replace native bcrypt with pure JavaScript bcryptjs:
npm uninstall bcrypt
npm install bcryptjs

# Scenario C: Use prebuilt binaries instead of compiling from source:
npm install sqlite3 --build-from-source=false

Step 3: Install Required System C/C++ Libraries (e.g., Canvas & Sharp)

If installing graphical, audio, or database packages that depend on system-level graphics engines, install the necessary development headers.

# Required dependencies for node-canvas (Debian / Ubuntu):
sudo apt-get install -y libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

# Required dependencies for node-canvas (macOS via Homebrew):
brew install pkg-config cairo pango libpng jpeg giflib librsvg

# Purge npm cache and clean node_modules:
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Verification & Testing Steps

Confirm that native addons compile successfully and that your application runs without C++ binding exceptions.

# 1. Verify node-gyp binary can query build environment:
npx node-gyp --version

# 2. Re-run dependency installation:
npm install

# 3. Test running your application build or development server:
npm run build

Summary Comparison Table

Troubleshooting Approach	Target Root Cause	Applied Layer	Recommended Scenario
Install build-essential	Missing C/C++ compilers	Operating System Package Manager	Fresh Linux servers & Docker container builds
Migrate to Pure JS (e.g. sass)	Deprecated C++ bindings (V8 changes)	Project package.json	Modernizing legacy Node projects (Node 18+)
Install Graphics C Headers	Missing system libraries (cairo/pango)	OS Development Headers	Packages utilizing image processing (e.g. canvas)
npm config set python	Python interpreter path mismatch	Global npm Configuration	Environments with multiple custom Python versions