From 685172b232bf031b0a834895a489b8b735daf399 Mon Sep 17 00:00:00 2001 From: Luke Sandberg Date: Fri, 6 Feb 2026 23:51:39 -0800 Subject: [PATCH 1/3] Add a better error message for when turbopack cannot be loaded suggest running with `--webpack` when possible --- docs/01-app/03-api-reference/08-turbopack.mdx | 18 ++++++++++++++++++ packages/next/errors.json | 7 ++++++- packages/next/src/build/swc/index.ts | 11 +++++++---- .../next/src/build/turbopack-analyze/index.ts | 9 +++++++++ .../next/src/build/turbopack-build/impl.ts | 11 +++++++++++ .../src/server/dev/hot-reloader-turbopack.ts | 12 ++++++++++++ .../turbo-tasks-backend/src/backend/mod.rs | 2 +- 7 files changed, 64 insertions(+), 6 deletions(-) diff --git a/docs/01-app/03-api-reference/08-turbopack.mdx b/docs/01-app/03-api-reference/08-turbopack.mdx index e163754f35f0..e28cf7a92b3d 100644 --- a/docs/01-app/03-api-reference/08-turbopack.mdx +++ b/docs/01-app/03-api-reference/08-turbopack.mdx @@ -16,6 +16,24 @@ We built Turbopack to push the performance of Next.js, including: - **Incremental Computation:** Turbopack parallelizes work across cores and **caches** results down to the function level. Once a piece of work is done, Turbopack won’t repeat it. - **Lazy Bundling:** Turbopack only bundles what is actually requested by the dev server. This lazy approach can reduce initial compile times and memory usage. +## Supported platforms + +Turbopack requires platform-specific native bindings. The following platforms are currently supported: + +| Platform | Architecture | +| -------------- | ---------------- | +| macOS (Darwin) | x64, ARM64 | +| Windows | x64, ARM64, ia32 | +| Linux (glibc) | x64, ARM64 | +| Linux (musl) | x64, ARM64 | + +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**. On these platforms, use the `--webpack` flag: + +```bash +next dev --webpack +next build --webpack +``` + ## Getting started Turbopack is now the **default bundler** in Next.js. No configuration is needed to use Turbopack: diff --git a/packages/next/errors.json b/packages/next/errors.json index b7fa362eb4db..8d50c432cf6b 100644 --- a/packages/next/errors.json +++ b/packages/next/errors.json @@ -1045,5 +1045,10 @@ "1044": "No router instance found.\nYou should only use \"next/router\" on the client side of your app.\n", "1045": "LRUCache: calculateSize returned %s%s, but size must be > 0. Items with size 0 would never be evicted, causing unbounded cache growth.", "1046": "`draftMode` must not be used within a Client Component. Next.js should be preventing `draftMode` from being included in Client Components statically, but did not in this case.", - "1047": "Extra keys returned from getStaticPaths in %s (%s) Expected: { paths: [], fallback: boolean }\\nSee here for more info: https://nextjs.org/docs/messages/invalid-getstaticpaths-value" + "1047": "Extra keys returned from getStaticPaths in %s (%s) Expected: { paths: [], fallback: boolean }\\nSee here for more info: https://nextjs.org/docs/messages/invalid-getstaticpaths-value", + "1048": "Turbopack analyze is not supported on this platform (%s/%s) because native bindings are not available. Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.\\n\\nFor more information, see: https://nextjs.org/docs/app/api-reference/turbopack#supported-platforms", + "1049": "Turbopack is not supported on this platform (%s/%s) because native bindings are not available. Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.\\n\\nTo use Next.js on this platform, use Webpack instead:\\n next dev --webpack\\n\\nFor more information, see: https://nextjs.org/docs/app/api-reference/turbopack#supported-platforms", + "1050": "Turbopack is not supported on this platform (%s/%s) because native bindings are not available. Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.\\n\\nTo build on this platform, use Webpack instead:\\n next build --webpack\\n\\nFor more information, see: https://nextjs.org/docs/app/api-reference/turbopack#supported-platforms", + "1051": "Turbopack trace server is not supported on this platform (%s/%s) because native bindings are not available. Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.", + "1052": "Turbopack is not supported on this platform (%s/%s) because native bindings are not available. Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings. Use the --webpack flag instead." } diff --git a/packages/next/src/build/swc/index.ts b/packages/next/src/build/swc/index.ts index 857a8e0a5059..b406bb20314b 100644 --- a/packages/next/src/build/swc/index.ts +++ b/packages/next/src/build/swc/index.ts @@ -108,11 +108,11 @@ const triples = (() => { if (rawTargetTriple) { Log.warn( - `Trying to load next-swc for target triple ${rawTargetTriple}, but there next-swc does not have native bindings support` + `next-swc does not have native bindings support for target triple ${rawTargetTriple}. Native features like Turbopack will not be available.` ) } else { Log.warn( - `Trying to load next-swc for unsupported platforms ${PlatformName}/${ArchName}` + `next-swc does not have native bindings for platform ${PlatformName}/${ArchName}. Native features like Turbopack will not be available.` ) } @@ -1292,7 +1292,9 @@ async function loadWasm(importPath = '') { _turboEngineOptions?: TurboEngineOptions | undefined ): Promise { throw new Error( - '`turbo.createProject` is not supported by the wasm bindings.' + `Turbopack is not supported on this platform (${PlatformName}/${ArchName}) because native bindings are not available. ` + + `Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings. ` + + `Use the --webpack flag instead.` ) }, startTurbopackTraceServer( @@ -1300,7 +1302,8 @@ async function loadWasm(importPath = '') { _port: number | undefined ): void { throw new Error( - '`turbo.startTurbopackTraceServer` is not supported by the wasm bindings.' + `Turbopack trace server is not supported on this platform (${PlatformName}/${ArchName}) because native bindings are not available. ` + + `Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.` ) }, }, diff --git a/packages/next/src/build/turbopack-analyze/index.ts b/packages/next/src/build/turbopack-analyze/index.ts index 18ba3fa0612b..55e98d845a84 100644 --- a/packages/next/src/build/turbopack-analyze/index.ts +++ b/packages/next/src/build/turbopack-analyze/index.ts @@ -35,6 +35,15 @@ export async function turbopackAnalyze( const startTime = process.hrtime() const bindings = await loadBindings(config?.experimental?.useWasmBinary) + + if (bindings.isWasm) { + throw new Error( + `Turbopack analyze is not supported on this platform (${process.platform}/${process.arch}) because native bindings are not available. ` + + `Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.\n\n` + + `For more information, see: https://nextjs.org/docs/app/api-reference/turbopack#supported-platforms` + ) + } + const dev = false const supportedBrowsers = getSupportedBrowsers(dir, dev) diff --git a/packages/next/src/build/turbopack-build/impl.ts b/packages/next/src/build/turbopack-build/impl.ts index 5363b831bbf1..f93b5d2f2050 100644 --- a/packages/next/src/build/turbopack-build/impl.ts +++ b/packages/next/src/build/turbopack-build/impl.ts @@ -125,6 +125,17 @@ export async function turbopackBuild(): Promise<{ const startTime = process.hrtime() const bindings = getBindingsSync() // our caller should have already loaded these + + if (bindings.isWasm) { + throw new Error( + `Turbopack is not supported on this platform (${process.platform}/${process.arch}) because native bindings are not available. ` + + `Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.\n\n` + + `To build on this platform, use Webpack instead:\n` + + ` next build --webpack\n\n` + + `For more information, see: https://nextjs.org/docs/app/api-reference/turbopack#supported-platforms` + ) + } + const dev = false const supportedBrowsers = getSupportedBrowsers(dir, dev) diff --git a/packages/next/src/server/dev/hot-reloader-turbopack.ts b/packages/next/src/server/dev/hot-reloader-turbopack.ts index 997ee5f50232..91f655c5906d 100644 --- a/packages/next/src/server/dev/hot-reloader-turbopack.ts +++ b/packages/next/src/server/dev/hot-reloader-turbopack.ts @@ -202,6 +202,18 @@ export async function createHotReloaderTurbopack( const bindings = getBindingsSync() + // Turbopack requires native bindings and cannot run with WASM bindings. + // Detect this early and give a clear, actionable error message. + if (bindings.isWasm) { + throw new Error( + `Turbopack is not supported on this platform (${process.platform}/${process.arch}) because native bindings are not available. ` + + `Only WebAssembly (WASM) bindings were loaded, and Turbopack requires native bindings.\n\n` + + `To use Next.js on this platform, use Webpack instead:\n` + + ` next dev --webpack\n\n` + + `For more information, see: https://nextjs.org/docs/app/api-reference/turbopack#supported-platforms` + ) + } + // For the debugging purpose, check if createNext or equivalent next instance setup in test cases // works correctly. Normally `run-test` hides output so only will be visible when `--debug` flag is used. if (isTestMode) { diff --git a/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs b/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs index 934744bb5ba4..f995dc9eca30 100644 --- a/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs +++ b/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs @@ -1316,7 +1316,7 @@ impl TurboTasksBackendInner { let elapsed = start.elapsed(); // avoid spamming the event queue with information about fast operations - if elapsed > Duration::from_secs(10) { + if elapsed > Duration::from_secs(0) { turbo_tasks().send_compilation_event(Arc::new(TimingEvent::new( "Finished writing to filesystem cache".to_string(), elapsed, From 5dfbfd5d5b64458efb92d1c463d425ae5089e8c1 Mon Sep 17 00:00:00 2001 From: Luke Sandberg Date: Sat, 7 Feb 2026 09:24:43 -0800 Subject: [PATCH 2/3] drop ia32, it is obsolete --- docs/01-app/03-api-reference/08-turbopack.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/01-app/03-api-reference/08-turbopack.mdx b/docs/01-app/03-api-reference/08-turbopack.mdx index e28cf7a92b3d..4c7ef7873700 100644 --- a/docs/01-app/03-api-reference/08-turbopack.mdx +++ b/docs/01-app/03-api-reference/08-turbopack.mdx @@ -20,12 +20,12 @@ We built Turbopack to push the performance of Next.js, including: Turbopack requires platform-specific native bindings. The following platforms are currently supported: -| Platform | Architecture | -| -------------- | ---------------- | -| macOS (Darwin) | x64, ARM64 | -| Windows | x64, ARM64, ia32 | -| Linux (glibc) | x64, ARM64 | -| Linux (musl) | x64, ARM64 | +| Platform | Architecture | +| -------------- | ------------ | +| macOS (Darwin) | x64, ARM64 | +| Windows | x64, ARM64 | +| Linux (glibc) | x64, ARM64 | +| Linux (musl) | x64, ARM64 | 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**. On these platforms, use the `--webpack` flag: From 8ea9c4b30040189a707fd6b882ed71d0db3f7479 Mon Sep 17 00:00:00 2001 From: Luke Sandberg Date: Mon, 9 Feb 2026 11:39:54 -0800 Subject: [PATCH 3/3] Update mod.rs --- turbopack/crates/turbo-tasks-backend/src/backend/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs b/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs index f995dc9eca30..934744bb5ba4 100644 --- a/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs +++ b/turbopack/crates/turbo-tasks-backend/src/backend/mod.rs @@ -1316,7 +1316,7 @@ impl TurboTasksBackendInner { let elapsed = start.elapsed(); // avoid spamming the event queue with information about fast operations - if elapsed > Duration::from_secs(0) { + if elapsed > Duration::from_secs(10) { turbo_tasks().send_compilation_event(Arc::new(TimingEvent::new( "Finished writing to filesystem cache".to_string(), elapsed,