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 errorCommon 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 ciUse a platform with prebuilds
- Switch to a glibc base image if prebuilds target glibc, not musl.
- Pin a Node major the package publishes prebuilds for.
- 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.