prebuild-install Network Failure Falls Back to Source - Fix Native Fetch in CI

prebuild-install downloads a precompiled native binary for your platform, falling back to a node-gyp source build if the download fails. A transient network/CDN error on the download forces the source path - which then fails on a slim runner with no compiler.

What this error means

Install logs show prebuild-install could not fetch the prebuilt binary (a timeout, 404, or reset), then attempts a source compile that fails because the toolchain is missing. A retry on a healthy network often downloads the prebuild and avoids compiling entirely.

npm output

prebuild-install warn install GET https://.../some-native-v3.0.0-napi.tar.gz
failed: connect ETIMEDOUT
prebuild-install warn install No prebuilt binaries found (falling back to source)
gyp ERR! build error
npm error code 1

Common causes

A transient download failure for the prebuilt binary

prebuild-install fetches the binary from a CDN/release host. A timeout, reset, or 5xx there aborts the download and triggers the source fallback.

The source fallback lacks a toolchain

Once it falls back, node-gyp needs a C/C++ compiler, make, and Python. A slim image without them fails the compile.

How to fix it

Retry the download, or supply build tools

Re-run so the prebuild fetch succeeds, or install a toolchain so the fallback can compile.

Terminal

# transient: retry the job (the prebuild usually downloads)
# or make the fallback buildable:
apt-get update && apt-get install -y python3 make g++
npm ci

Make native installs resilient

Use a base image with a C/C++ toolchain + Python for native deps.
Match the image OS/libc/arch to the package’s published prebuilds.
Cache built native modules per platform to avoid repeat fetches.

How to prevent it

Keep a toolchain available for prebuild source fallbacks.
Match image platform to available prebuilds.
Retry transient native-binary downloads.