npm node-gyp Build Failed in CI - Fix Native Addon Compilation

By Daniel Zoghalchali·Latchkey

node-gyp compiles native addons from source when no prebuilt binary is available. The build needs a C/C++ toolchain and Python, and it fails when those are missing on the runner.

What this error means

During install a package with native code fails with gyp ERR! build error and a make or compiler error. It often appears only in CI because the local machine already has build tools installed.

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack at ChildProcess.onExit
gyp ERR! System Linux
npm ERR! code 1

Common causes

No compiler toolchain on the runner

node-gyp needs gcc/g++/make (build-essential) to compile the addon, and a minimal image often lacks them.

Missing or wrong Python

node-gyp drives the build through Python; an absent or incompatible Python breaks configuration before compilation.

How to fix it

Install the build toolchain

1. Install build-essential and python3 before npm install.
2. Re-run the install so node-gyp can compile.

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

Prefer a prebuilt binary when available

1. Pin a package version that ships prebuilt binaries for your platform.
2. This avoids compiling from source entirely.

How to prevent it

• Use a runner image that already includes a C/C++ toolchain and Python, or install them in a cached setup step, so native addons compile reliably.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation