Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Next.js cannot load its SWC compiler binary

ErrorFailed to load SWC binary

Short answer

Next.js compiles with SWC, a native binary shipped as an optional npm package for your platform. The error means that package was not installed or cannot run. Reinstall without skipping optional dependencies, regenerate a lockfile made on another platform, or install the Visual C++ runtime on Windows.

  • Applies to Next.js 15, Node.js 22, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print your platform and check that the matching @next/swc package is in node_modules.

    node -p "process.platform + ' ' + process.arch"
    ls node_modules/@next | grep swc
  2. 2Match what you see, then jump to its fix

    1. 1No @next/swc-* folder in node_modulesOptional dependencies were skippedFix
    2. 2Works on your laptop, fails in CI or DockerThe lockfile was made on another platformFix
    3. 3After switching Node.js versions or moving between Intel and Apple siliconnode_modules built for a different CPU architectureFix
    4. 4Fails on Windows with the platform package presentWindows is missing the Visual C++ RedistributableFix

What does the error look like?

  • Failed to load SWC binary

Cause 1 of 4

Optional dependencies were skipped

1Check

The SWC binary comes as an optional dependency. Package managers skip those when told to.

npm config get omit
echo "$NPM_CONFIG_OMIT"

2Fix

Install again without omitting optional packages (drop --no-optional or --omit=optional), from a clean node_modules.

rm -rf node_modules
npm install

3Verify

The platform package is present and the dev server starts.

ls node_modules/@next | grep swc
npx next dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

The lockfile was made on another platform

1Check

A lockfile generated on one OS can list only that platform's optional packages, so CI cannot install its own.

grep -c "@next/swc" package-lock.json

2Fix

Delete the lockfile and regenerate it, using a current npm.

npm i -g npm@latest
rm package-lock.json
npm install

3Verify

Run the same install in CI or in a fresh container and start the build.

npm ci && npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

node_modules built for a different CPU architecture

1Check

The page describes this for an M1 Mac after switching to a Node.js build with arm64 support: the installed swc package no longer matches.

node -p "process.arch"

2Fix

Reinstall dependencies with force so the right package is fetched.

npm i --force

3Verify

Start the dev server again.

npx next dev

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

Windows is missing the Visual C++ Redistributable

1Check

The native binary needs the Microsoft Visual C++ Redistributable.

dir node_modules\@next

2Fix

Install the latest supported Visual C++ Redistributable from Microsoft, then run the dev server again.

npx next dev

3Verify

The compile error is gone.

npx next build

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Do not use flags that skip optional dependencies in CI or Docker builds.
  • Commit a lockfile that was generated with a current npm.
  • Reinstall dependencies after changing Node.js version or machine architecture.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.