ErrorVaultHQ

Solved Error

How to Fix: Next.js Turbopack build failed: Unsupported syntax or architecture

Quick Fix

Fastest fix: fall back to Webpack for the build while you isolate the cause. 1. Run without Turbopack. Use next build --webpack (Next.js 16) or simply drop the --turbo / --turbopack flag (Next.js 15 and earlier). If the build succeeds, the error is confirmed to be a Turbopack-specific incompatibility, not a bug in your actual code. 2. Delete caches and reinstall. Run rm -rf .next node_modules then reinstall dependencies fresh, so any wrong-architecture native binaries get replaced with the correct ones for your machine. 3. If it still fails under webpack too, the problem is your code/config, not Turbopack — check the steps below for the specific package causing it.

What this error means

Turbopack is Next.js's Rust-based bundler. Unlike webpack, Turbopack requires platform-specific native bindings to run, and it parses every file it bundles as JavaScript/TypeScript/CSS source code. When Turbopack's build graph ends up including a file that is actually a compiled binary executable (not text) — for example a native .node addon, or a vendor binary like esbuild's or SWC's platform-specific package (e.g. @esbuild/darwin-x64/bin/esbuild) — it tries to read that binary as source code and fails, because the byte content is not valid syntax for any architecture Turbopack understands. This is reported in real bug reports as things like 'Reading source code for parsing failed' with an invalid UTF-8 sequence, which is the same underlying class of problem as 'Unsupported syntax or architecture.' There are two distinct root causes worth checking, plus a fallback if neither applies.

Step-by-Step Guide

Cause 1: A native/binary dependency is being bundled by mistake

  1. 1Mark the package as external. This happens when a package that ships a compiled binary (esbuild, SWC forks, sharp, Prisma's query engine, or your own compiled Rust/native .node addon) is imported into a Server Component, Route Handler, or otherwise gets pulled into Turbopack's module graph instead of being treated as an external package. In next.config.js, add the offending package name to serverExternalPackages so Turbopack does not try to bundle/parse it: module.exports = { serverExternalPackages: ['esbuild', 'sharp'] }. Note: even with this set, some native-binary packages still trigger the error in current Turbopack versions — this is a confirmed, tracked issue for packages like esbuild when imported inside Server Components or Route Handlers.
  2. 2Check for a native addon in a monorepo/workspace. If you build a Rust/native module in a separate workspace package (common with pnpm workspaces) and import it into your Next.js app, Turbopack can fail to find or correctly load the compiled addon for your platform. Confirm the addon was built for your current OS/architecture, and try importing it only from server-only code paths, never from a file that could end up in the client bundle.
  3. 3Avoid importing binary-shipping tools directly in app code. If you only need esbuild, sharp, etc. for a build script or a one-off server task, call it from a separate Node script or an API route that is fully excluded from the Turbopack graph, rather than importing it inline in a Server Component.

Cause 2: Wrong-architecture binary installed (mismatched OS/CPU)

  1. 1Never copy node_modules between platforms. Packages like esbuild and SWC ship separate native binaries per OS and CPU architecture (darwin-x64, darwin-arm64, linux-x64-gnu, linux-arm64-musl, win32-x64, etc.). If node_modules was installed on one machine/OS and then copied to another (common with Docker images, WSL, CI caches, or copying a project between an Intel and Apple Silicon Mac), the wrong binary ends up on disk and Turbopack chokes trying to read it. Delete node_modules entirely and run a fresh npm install, pnpm install, or yarn install on the actual target machine or inside the target Docker image/architecture.
  2. 2In Docker, match the build stage architecture to the runtime architecture (e.g. do not build on an ARM host and run the container on x64, or vice versa, without a multi-arch build).
  3. 3Manually reinstall the correct native package if npm skipped it, e.g. npm install @next/swc-linux-x64-gnu or the equivalent esbuild/@swc package for your exact OS and libc (glibc vs musl).
  4. 4Check for optional-dependency install issues. If you use npm ci with --omit=optional or similar flags, or a lockfile generated on a different OS, the optional native binaries for your platform may never get installed at all.

Cause 3: Your OS/CPU is not supported by Turbopack's native bindings at all

  1. 1Switch to webpack explicitly. Turbopack requires platform-specific native bindings. On platforms without native bindings (e.g. FreeBSD, OpenBSD), Next.js falls back to WebAssembly (WASM) bindings. WASM bindings support core SWC features like compilation and minification, but do not support Turbopack. If you are on one of these platforms, or an otherwise unsupported OS/CPU combination, Turbopack cannot run at all, and this is the real cause of the failure. On these platforms, use the --webpack flag. In package.json, set your scripts to "dev": "next dev --webpack" and "build": "next build --webpack".
  2. 2Check if your OS and CPU are supported. Confirm your platform is genuinely unsupported by checking your OS and CPU architecture against the Next.js Turbopack documentation before spending more time debugging — this is expected, permanent behavior on those platforms, not a bug you can patch.

General fallback and escalation

Fall back to webpack if you are on a deadline: If you hit an incompatibility (custom webpack(config), unsupported plugin), fall back to Webpack: next dev --webpack / next build --webpack in Next.js 16, or drop the --turbo flag in Next.js 15. Update Next.js. Turbopack compatibility is improving rapidly release-to-release; run npm i next@latest and retest, since many binary/native-module bugs are fixed in newer versions. Get a trace for a bug report. If you need to file an issue, you can generate a trace file by appending NEXT_TURBOPACK_TRACING=1 to your dev command, which will produce a .next/dev/trace-turbopack file — include that file when creating a GitHub issue on the Next.js repo to help investigate. File or search the official tracker. Errors involving native binaries and Turbopack (esbuild, native .node addons in workspaces, node-config, etc.) are actively tracked as confirmed Turbopack team issues on the vercel/next.js GitHub repository — search there for your exact package name before assuming it's something only you are hitting. When to get different help: if the build also fails under plain webpack with the same error, the problem is in your code, a corrupted dependency, or a genuinely broken native binary install — not Turbopack — and you should focus troubleshooting on that specific package's own installation instructions instead.

Sources:

Heads up: this guide was drafted with AI assistance from the real sources listed below, and structured by our team for clarity. It may not cover every possible cause — if it doesn't fix your issue, let us know and we'll take a closer look. See how we create our fixes.

Was this fix helpful?

Related Error Fixes