prebuild-install "WARN install … falling back to source compile" - Fix in CI

prebuild-install fetches a prebuilt native binary for your platform and Node ABI; when none matches it warns and falls back to compiling from source. The failure is that fallback compile hitting a missing toolchain.

What this error means

Install logs show prebuild-install WARN install and a fallback to building from source, which then fails (often the familiar node-gyp/compiler error). Common on musl/Alpine, arm64, or a Node ABI with no published prebuild.

prebuild-install WARN install No prebuilt binaries found
(target=20.0.0 runtime=node arch=arm64 platform=linux libc=musl)
prebuild-install WARN install falling back to source compile with node-gyp
gyp ERR! build error

Common causes

No prebuild for this platform/arch/ABI

The package publishes prebuilds only for some targets. On musl, arm64, or a newer Node ABI, none matches and prebuild-install falls back to source.

The fallback compile lacks a toolchain

Once it falls back, it needs Python and a C/C++ compiler. On a slim image those are absent, so the source build fails.

The prebuilt binary host was unreachable

prebuild-install downloads from a remote host (often GitHub releases). A network failure or 404 there forces the source path.

How to fix it

Provide the toolchain for the fallback

Install build tools so a source compile can succeed when no prebuild matches.

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

Use a platform with prebuilds

1. Switch to a glibc base image if prebuilds target glibc, not musl.
2. Pin a Node major the package publishes prebuilds for.
3. Retry if the binary host timed out - the prebuild path skips compiling entirely.

How to prevent it

• Match image libc/arch/Node ABI to the package’s prebuilds.
• Keep a C/C++ toolchain available for source fallbacks.
• Cache compiled native modules per platform.

Related guides