Node "@swc/core platform binary missing" in CI

@swc/core loads a native binding from a platform-specific package (e.g. @swc/core-linux-x64-gnu). When that optional package is missing, swc fails with "Failed to load native binding".

What this error means

A build or test using swc fails with "Failed to load native binding" or "Cannot find module '@swc/core-linux-x64-gnu'". It runs locally where the matching platform package was installed.

node

Error: Failed to load native binding
    at Object.<anonymous> (/work/repo/node_modules/@swc/core/binding.js:1:1)
Cannot find module '@swc/core-linux-x64-gnu'

Common causes

Optional platform package not installed

The @swc/core-<platform> optional dependency was skipped, so no native binding loads.

libc mismatch (gnu vs musl)

On Alpine, swc needs the -musl variant; the -gnu package present cannot load.

How to fix it

Install optional deps for the right platform

Include optional dependencies so the correct @swc/core-<platform> package installs.

Terminal

npm ci --include=optional

Match the libc variant to the image

On Alpine use a base/runner that pulls the -musl binding, or switch to a glibc image.

Use a glibc image for the -gnu binding, or Alpine for -musl.
Ensure the lockfile records the platform you build on.
Reinstall after changing the base image.

How to prevent it

Keep optional dependencies enabled so platform bindings install.
Match the libc variant (gnu/musl) to the base image.
Latchkey self-healing managed runners auto-retry transient native-binding download failures and cache platform packages so swc loads cleanly.