Add a better error message for when turbopack cannot be loaded

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   |
+| 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:

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."
 }

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,15 +1292,18 @@ async function loadWasm(importPath = '') {
         _turboEngineOptions?: TurboEngineOptions | undefined
       ): Promise<Project> {
         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(
         _traceFilePath: string,
         _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.`
         )
       },
     },

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)

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)

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) {