Next.js "Failed to load SWC binary for linux/x64" in CI

By Kaveh Alemi·Latchkey

Next.js compiles with SWC, a native binary shipped as platform-specific optional dependencies. If the binary for the CI platform was not installed (commonly because a lockfile was generated on a different OS), the build fails to load SWC.

What this error means

next build fails with "Failed to load SWC binary for linux/x64" and a hint about patching the lockfile, often after the lockfile was committed from macOS or Windows.

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

Common causes

The platform-specific SWC optional dep is missing

npm records the host platform's optional dependencies; a lockfile from another OS omits the linux/x64 SWC binary the runner needs.

Optional dependencies were skipped during install

Installing with optional dependencies disabled prevents the native SWC package from being fetched.

How to fix it

Regenerate the lockfile to include all platforms

1. Ensure npm ci installs optional dependencies (do not pass --no-optional).
2. If the lockfile lacks the linux binary, regenerate it so optional deps for all platforms are recorded.
3. Commit the updated lockfile and re-run CI.

rm -rf node_modules package-lock.json
npm install
git add package-lock.json

Install optional dependencies in CI

Confirm CI does not skip optionals so the SWC binary is fetched.

npm ci   # keep optional dependencies enabled

How to prevent it

• Keep optional dependencies enabled in CI installs.
• Generate the lockfile so it records all needed platforms.
• Match the local and CI Node and OS where practical.

Frequently asked questions

Related guides

References

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