node-pre-gyp "Prebuilt binary … not found" - Fix Native Fallback in CI

node-pre-gyp downloads a prebuilt native binary for your platform if one exists, and falls back to compiling from source otherwise. The failure is usually no prebuild for your OS/arch plus a toolchain gap on the fallback.

What this error means

Install logs show node-pre-gyp could not find a prebuilt binary, tries a source compile, and that compile fails (often the same toolchain gap as node-gyp). Common on Alpine/musl and arm64 where prebuilds are absent.

npm output

node-pre-gyp WARN Pre-built binaries not found for some-pkg@2.0.0 and node@20
node-pre-gyp WARN Hit error Connection timed out / 404
gyp ERR! build error
npm error code 1

Common causes

No prebuild for this platform/arch/Node ABI

The package only publishes prebuilds for certain platforms. On musl, arm64, or a newer Node ABI, none matches and it falls back to source.

The fallback source build lacks a toolchain

Once it falls back, it needs a C/C++ compiler, make, and Python - missing on slim images, so the source compile fails too.

The prebuilt binary host was unreachable

node-pre-gyp fetches binaries from a remote host (often S3). A network/404 there forces the source path.

How to fix it

Provide the toolchain for the fallback

Install build tools so the source compile can succeed.

Terminal

apt-get update && apt-get install -y python3 make g++
npm ci

Pick a platform with prebuilds

Use a glibc base image if prebuilds only target glibc, not musl.
Pin a Node major that the package publishes prebuilds for.
Retry if the binary host timed out; the prebuild path avoids compiling entirely.

How to prevent it

Match image libc/arch/Node to the package’s prebuilds.
Keep a toolchain available for source fallbacks.
Cache compiled modules per platform to avoid repeat builds.