Next.js "Failed to load SWC binary": the real fix

TL;DR#

Next.js needs a native @next/swc-* binary matching your OS, CPU and C library; it ships as an optionalDependency of next and npm only installs the variant that fits the platform it runs npm install on. If node_modules was built on a different platform — a different machine, a different base Docker image, or a lockfile regenerated elsewhere — the binary for your platform is simply absent, and next dev or next build reports it cannot load SWC (current Next.js shows "Attempted to load @next/swc-linux-x64-gnu, but an error occurred" or "…but it was not installed"; an older release shows the shorter "Failed to load SWC binary for linux/x64, see more info here: https://nextjs.org/docs/messages/failed-loading-swc"). The fix is not editing next.config.js: delete package-lock.json and node_modules, then run npm install on the platform that will actually run Next.js.

Why it happens#

Next.js replaced Babel with a Rust compiler, SWC, enabled by default since Next.js 12. SWC itself is not pure JavaScript: Next.js ships it as a set of prebuilt native binaries, one package per platform (@next/swc-linux-x64-gnu, @next/swc-linux-x64-musl, @next/swc-darwin-arm64, @next/swc-win32-x64-msvc, and so on), listed as optionalDependencies of the next package itself. npm install only downloads the one optional dependency that matches the machine it is running on; the others are skipped. That is efficient — you are not shipping every platform's binary — but it means node_modules/@next/ only ever contains the binary for the platform where npm install last ran.

The official error page traces this directly to that mechanism: "your package manager (e.g. npm) might have generated a lockfile that only includes optionalDependencies specific to the platform it was generated on, preventing the optionalDependency needed for CI from being installed." The two platform details that most often diverge between where node_modules was created and where Next.js is asked to run it:

• The C library, not the CPU architecture. @next/swc-linux-x64-gnu links against glibc; @next/swc-linux-x64-musl links against musl. A node_modules folder built inside a Debian- or Ubuntu-based image (glibc) and then copied, or bind-mounted, into an Alpine image (musl) has the gnu binary on disk but needs the musl one — the architecture is identical, only the libc differs, so this is easy to miss when the Dockerfile uses different base images for the build and runtime stages.
• The OS itself, when a project is set up on one platform (say Windows or macOS) and its node_modules is copied as-is into a Linux CI runner or container instead of being reinstalled there.

Reproduced on Next.js 16.4.2, Docker Desktop, 16 October 2026: a next + react + react-dom project was installed with npm install inside node:20-bookworm-slim (glibc). node_modules/@next/ ended up containing only swc-linux-x64-gnu — npm's platform filtering is working as intended, it simply filtered for the install-time platform. Mounting that same, unmodified node_modules into node:20-alpine (musl) and running next build produced:

⚠ Attempted to load @next/swc-linux-x64-gnu, but an error occurred: Error loading shared library ld-linux-x86-64.so.2: No such file or directory (needed by /app/node_modules/@next/swc-linux-x64-gnu/next-swc.linux-x64-gnu.node)
⚠ Attempted to load @next/swc-linux-x64-musl, but it was not installed
  Downloading swc package @next/swc-wasm-nodejs... to /root/.cache/next-swc

Next.js did not stop there: on a current install it automatically downloads a WebAssembly fallback build of SWC (@next/swc-wasm-nodejs) rather than failing outright. On this version the build still failed, but for a second, more specific reason — Turbopack, the default bundler since Next.js 16, refuses to run on WASM-only bindings:

Error: Turbopack is not supported on this platform (linux/x64) because native bindings are not available. Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.
 
To build on this platform, use Webpack instead:
  next build --webpack

That second message is new compared with the 2021-era question this error is best known from: it exists only because Turbopack, which did not exist yet in 2021, now needs the native binary and has no WASM path of its own.

Fix#

1. Delete the lockfile and node_modules, then reinstall on the platform that will run Next.js. This is the accepted answer (score 182) to the original Stack Overflow question (93 votes), and it is what the reproduction above confirms: the broken install had swc-linux-x64-gnu on disk; deleting everything and reinstalling inside the Alpine (musl) container produced swc-linux-x64-musl instead, and the build succeeded.

   bash

   rm -rf node_modules package-lock.json
   npm install

   If you use Docker, run this step inside the same base image you ship, not on the host, and not in an earlier build stage with a different image. A multi-stage Dockerfile that runs npm install in one FROM node:20-bookworm-slim stage and then COPYs node_modules into a FROM node:20-alpine runtime stage reproduces exactly the failure above — either reinstall in the final stage, or keep both stages on the same base image.

2. If optional dependencies were disabled, re-enable them. npm skips every optionalDependency, including the SWC binaries, when the install explicitly omits them:

   bash

   npm install --omit=optional
   npm install

   The first line reproduces the missing-binary error on any platform, because it skips every optional dependency, not only the SWC one; the second line, run without that flag, lets the SWC optionalDependency install as usual. --omit=optional is npm's current flag for what older npm releases called --no-optional; both end up marking optional as an omitted dependency type in npm's own install logic.

3. Upgrade npm if the lockfile predates per-platform optionalDependencies filtering. The official error page attributes stale platform-only lockfiles to an old npm version and recommends npm i -g npm@latest before regenerating the lockfile — this is a second cause of the same symptom, distinct from steps 1 and 2, and worth trying if a fresh npm install on the right platform still does not produce the binary you expect.

4. On Windows, confirm the Microsoft Visual C++ Redistributable is installed. This is specific to the Windows native binary (@next/swc-win32-x64-msvc) and is documented by Next.js itself; it cannot be verified from this reproduction, which ran on Linux containers, so take it as the vendor states it, not as independently confirmed here.

Two remedies that circulate for this error are not effective on a current Next.js install, and prescribing them is the kind of fix that quietly stops working after an upgrade:

• swcMinify: false in next.config.js. This key controlled whether SWC or Terser minified production output from Next.js 12 through 14. Next.js 15 enabled that behaviour by default and removed the deprecated option; setting it today changes nothing about whether the native binary loads, because minification and binary loading are unrelated steps.
• Installing @swc/core or @swc/cli (sometimes suggested for a Docker build). Those are the general-purpose SWC packages, separate from the @next/swc-* bindings that next itself depends on as optionalDependencies. Adding @swc/core to a Dockerfile does not put a @next/swc-* binary into node_modules/@next/.

A .babelrc with the next/babel preset still opts the JavaScript/TypeScript transform out of SWC and onto Babel, as the Next.js Compiler documentation describes — but on a current install this does not remove the need for the native binding that Turbopack itself depends on, so it is not a substitute for reinstalling on the right platform if Turbopack is in use.

Verify the fix#

After reinstalling, confirm the binary actually matching your platform exists before retrying the build:

ls node_modules/@next/ | grep swc

On the reproduction above, this went from swc-linux-x64-gnu only, to swc-linux-x64-musl only, after the reinstall inside the Alpine container — then next build compiled and generated the static routes without any SWC warning.

If you are inside Docker specifically#

The fastest way to confirm whether this is a build-stage/runtime-stage mismatch: check the base image name in every FROM line of the Dockerfile. node:<version>-alpine uses musl; node:<version>, node:<version>-slim and node:<version>-bookworm-slim use glibc. Running npm install in one and copying node_modules into the other is the single most common way this error reaches a container that worked fine on a developer's own machine. If the error instead changes shape entirely — the next build stage itself failing to resolve another Compose service by name, because the build container is not attached to the Compose network — you are past this error and into a different one: see the related Docker networking fix linked below.

If the project uses next start after a build that happened in a different stage or container from the one running next start, and the error has changed from an SWC load failure to Next.js reporting it cannot find a valid production build, that is a separate, unrelated failure: the build artifact itself did not reach the runtime folder, rather than SWC failing to load during the build.

A node_modules folder that looks complete but silently lost files it should have — the same class of defect as the missing SWC binary above — also shows up as Cannot find module 'caniuse-lite/dist/unpacker/agents': npm install reports the tree is healthy while a nested dist folder stays missing, and only a full reinstall (npm ci, or the delete-and-reinstall above) restores it. Both errors are solved by the same instinct: stop trusting an npm install that ran against a node_modules built somewhere else, and reinstall clean on the platform that matters.

Multi-stage Docker builds carry this same "works at build time, breaks at runtime" shape in other places too — for example a hostname that resolves while next dev reaches a Compose service by name, but the production build stage cannot, because the build runs outside the Compose network. Neither error is caused by SWC, but both are reminders that what a Next.js project needs at build time and what it needs at runtime are not always provided by the same stage.

Further reading: NextAuth login failed: handle CredentialsSignin, v4 and v5. Also see Fix: sh: 1: next: not found on Heroku.