SWC "Bindings not found" / wrong @swc/core platform in CI

By Kaveh Alemi·Latchkey

SWC ships its compiler as a platform-specific native binary. "Bindings not found" means the optional @swc/core-<platform> package for the runner's OS and architecture was not installed, so SWC has no engine to run.

What this error means

The build fails with "Error: Bindings not found." or a message that the @swc/core binary for the platform is missing on a Linux x64 or arm64 runner.

Error: Bindings not found.
Failed to load native binding for @swc/core on linux-x64-gnu.
Please ensure @swc/core-linux-x64-gnu is installed.

Common causes

The platform binary was excluded by the lockfile

A lockfile generated on macOS or Windows may omit the Linux optional dependency, so CI never installs the binary it needs.

Optional dependencies were skipped during install

Installing with --no-optional or a cache that dropped the platform package leaves SWC without its native binding.

How to fix it

Reinstall so the platform binary is fetched

1. Remove node_modules and the lockfile entry for the wrong platform if needed.
2. Reinstall on the target OS so the correct @swc/core-<platform> is added.
3. Re-run the build.

rm -rf node_modules
npm install

Do not skip optional dependencies

Ensure CI installs optional deps so the native binding for the runner platform is present.

npm ci --include=optional

How to prevent it

• Generate the lockfile so it includes all target platform binaries.
• Install optional dependencies in CI, not --no-optional.
• Key any node_modules cache on the runner OS and arch.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation