Next.js/SWC "Failed to load SWC binary" - Fix in CI

By Kaveh Alemi·Latchkey

Next.js compiles with SWC, a platform-specific native binary (@next/swc-<os>-<arch>) chosen at install time. When node_modules was installed on a different OS/arch, or the optional binary was skipped, Next cannot load it.

What this error means

The build fails with Failed to load SWC binary for <platform>/<arch> and a note to reinstall. It is consistent and tied to where node_modules was created or how it was installed.

next build output

Failed to load SWC binary for linux/x64, see more info here:
https://nextjs.org/docs/messages/failed-loading-swc

Error: Cannot find module '@next/swc-linux-x64-gnu'

Common causes

node_modules built on a different platform

A node_modules created on macOS/Windows (or restored from a cache for a different OS/arch) has the wrong @next/swc binary, so the Linux runner cannot load it.

Optional binary skipped at install

Installing with --no-optional, or a lockfile that omits the platform package, leaves Next without the SWC binary for the current platform.

glibc vs musl mismatch

On Alpine (musl) the build needs the -musl SWC variant; a glibc-built install fails to load on musl and vice versa.

How to fix it

Reinstall on the target platform

Remove the foreign tree and reinstall so Next fetches the correct SWC binary for the runner.

Terminal

rm -rf node_modules
npm ci   # installs the platform-correct @next/swc-<os>-<arch>

Match the libc variant and keep optional deps

On Alpine, use a glibc base image, or ensure the -musl SWC variant installs.
Do not install with --no-optional; the SWC binary is an optional dependency.
Scope any node_modules cache to the runner OS/arch.

How to prevent it

Never commit node_modules; install on the runner with npm ci.
Scope dependency caches to the runner OS/arch and libc.
Avoid --no-optional so the SWC binary is installed.

Frequently asked questions

What causes ""Failed to load SWC binary""?

A node_modules created on macOS/Windows (or restored from a cache for a different OS/arch) has the wrong @next/swc binary, so the Linux runner cannot load it.

How do I fix "Failed to load SWC binary"?