node-pre-gyp "--fallback-to-build failed" in CI

node-pre-gyp first tries to download a prebuilt binary, then falls back to compiling from source. In CI both can fail: the download is blocked or 404s, and the runner lacks the compiler to build.

What this error means

Install fails after node-pre-gyp reports it could not fetch a prebuilt binary and then could not build it. You see a download error followed by a node-gyp compile failure.

node-pre-gyp ERR! Tried to download(404): https://.../addon-v3-node-v115-linux-x64.tar.gz
node-pre-gyp WARN Pre-built binaries not installable for pkg
node-pre-gyp ERR! install --fallback-to-build failed

Common causes

Prebuilt binary unavailable or unreachable

No prebuild exists for this Node ABI/platform, or the download host is blocked, returning 404.

No toolchain for the source fallback

The fallback compile needs make, a compiler, and Python that the runner does not have.

How to fix it

Provision the build toolchain for the fallback

Install Python and a compiler so the source build can succeed when the prebuild is missing.

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

Pin a Node/package version with a matching prebuild

Align the Node version to one that has a published prebuilt binary so no compile is needed.

1. Check which Node ABI the package publishes prebuilds for.
2. Pin the Node version to match an available prebuild.
3. Ensure the prebuild host is reachable from the runner.

How to prevent it

• Match the Node version to a published prebuild for native packages.
• Keep a build toolchain available as a fallback.
• Latchkey self-healing managed runners auto-retry transient prebuilt-binary download failures and cache binaries so a flaky download does not force a slow source build.

Related guides