Node "prebuilt binary not found for musl" (Alpine) in CI

A native package publishes glibc prebuilds, but Alpine uses musl libc. With no musl prebuild and no compiler, the install fails on the libc mismatch.

What this error means

On an Alpine-based runner, a native dependency fails with "prebuilt binary not found" or a runtime "Error loading shared library ... musl". A Debian/Ubuntu runner installs the same package fine.

node

Error: prebuilt binary not found for pkg on linux-x64-musl

Error loading shared library ld-linux-x86-64.so.2: No such file or directory
(needed by /work/repo/node_modules/pkg/build/Release/addon.node)

Common causes

Package ships glibc-only prebuilds

The native package does not publish a musl variant, so Alpine has nothing compatible to download.

Alpine lacks the build toolchain to compile

Without build-base and python3, the source fallback cannot run on Alpine.

How to fix it

Use a glibc base image

Switch the runner image to a glibc distro (Debian/Ubuntu slim) so the published prebuilds apply.

Dockerfile

# Dockerfile
FROM node:20-bookworm-slim
# instead of node:20-alpine

Install musl build tools to compile from source

If you must stay on Alpine, add the toolchain so the native module builds for musl.

Terminal

apk add --no-cache build-base python3
npm ci

How to prevent it

Prefer glibc base images for projects with native dependencies.
Add build-base + python3 when Alpine is required.
Latchkey self-healing managed runners auto-retry transient prebuild download failures and offer glibc base images so musl/glibc mismatches do not block installs.