node-gyp "gyp ERR! build error" - Fix Native Module Compilation in CI

node-gyp compiles native C/C++ addons from source. In CI it fails when the runner lacks a C/C++ toolchain, Python, or the headers node-gyp needs to build against.

What this error means

Install fails compiling a native module (often with gyp ERR! build error and a non-zero make/node-gyp rebuild exit). The package has no prebuilt binary for this platform, so it falls back to building from source and the toolchain is missing.

npm output

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (.../node-gyp/lib/build.js)
npm error code 1
npm error path /app/node_modules/some-native-addon

Common causes

No C/C++ compiler on the runner

Minimal/Alpine images often lack gcc/g++/make. node-gyp cannot compile the addon without a toolchain.

Missing Python or build dependencies

node-gyp needs Python and platform build tools. A slim image without them fails at configure or build time.

No prebuilt binary for this platform/arch

Packages that normally ship prebuilds may have none for your OS/arch (e.g. Alpine musl, arm64), forcing a from-source build that needs the full toolchain.

How to fix it

Install the build toolchain

Add a compiler, make, and Python before installing.

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y python3 make g++
# Alpine
apk add --no-cache python3 make g++
npm ci

Prefer a prebuilt path

Use a base image that already includes build tools, or the package’s prebuilt-friendly variant.
On Alpine, consider a glibc image if prebuilds only target glibc.
Cache the compiled node_modules keyed on lockfile + platform to avoid rebuilding every run.

How to prevent it

Use CI images with a C/C++ toolchain for native deps.
Match the image libc/arch to available prebuilds.
Cache built native modules per platform.