turbopack: report an actionable error when Node.js child processes cannot connect

[lukesandberg]

What

Improve the error message reported when a Node.js worker process fails to connect to turbopack. Use a dedicated exit code to signal this.

Why

Tools like codex like to launch next in a sandbox with limited permissions. We cannot really support this but we can report more actionable error messages. The current error is awful:

FATAL: An unexpected Turbopack error occurred:
Failed to write app endpoint /page

Caused by:
- [project]/test/tmp/next-test-1791478247265-510/app/globals.css [app-client] (css)
- creating new process
- node process exited before we could connect to it with exit status: 0

Debug info:
- Execution of get_all_written_entrypoints_with_issues_operation failed
- Execution of EntrypointsOperation::new failed
- Execution of all_entrypoints_write_to_disk_operation failed
- Execution of output_assets_operation failed
- Execution of <AppEndpoint as Endpoint>::output failed
- Failed to write app endpoint /page
- Execution of AppEndpoint::output failed
- Execution of whole_app_module_graph_operation failed
- Execution of *Project::get_all_additional_entries failed
- Execution of ModuleGraph::from_graphs failed
- Execution of ModuleGraph::from_graphs_inner failed
- Execution of SingleModuleGraph::new_with_entries failed
- [project]/test/tmp/next-test-1791478247265-510/app/globals.css [app-client] (css)
- Execution of primary_chunkable_referenced_modules failed
- Execution of <CssModule as Module>::references failed
- Execution of parse_css failed
- Execution of <PostCssTransformedAsset as Asset>::content failed
- Execution of PostCssTransformedAsset::process failed
- Execution of evaluate_webpack_loader failed
- creating new process
- node process exited before we could connect to it with exit status: 0
  Process output:

  Process error output:

> Build error occurred
Error [TurbopackInternalError]: Failed to write app endpoint /page

Caused by:
- [project]/test/tmp/next-test-1791478247265-510/app/globals.css [app-client] (css)
- creating new process
- node process exited before we could connect to it with exit status: 0

Debug info:
- Execution of get_all_written_entrypoints_with_issues_operation failed
- Execution of EntrypointsOperation::new failed
- Execution of all_entrypoints_write_to_disk_operation failed
- Execution of output_assets_operation failed
- Execution of <AppEndpoint as Endpoint>::output failed
- Failed to write app endpoint /page
- Execution of AppEndpoint::output failed
- Execution of whole_app_module_graph_operation failed
- Execution of *Project::get_all_additional_entries failed
- Execution of ModuleGraph::from_graphs failed
- Execution of ModuleGraph::from_graphs_inner failed
- Execution of SingleModuleGraph::new_with_entries failed
- [project]/test/tmp/next-test-1791478247265-510/app/globals.css [app-client] (css)
- Execution of primary_chunkable_referenced_modules failed
- Execution of <CssModule as Module>::references failed
- Execution of parse_css failed
- Execution of <PostCssTransformedAsset as Asset>::content failed
- Execution of PostCssTransformedAsset::process failed
- Execution of evaluate_webpack_loader failed
- creating new process
- node process exited before we could connect to it with exit status: 0
  Process output:

  Process error output:
    at <unknown> (TurbopackInternalError: Failed to write app endpoint /page)
    at throwTurbopackInternalError (../../../packages/next/dist/shared/lib/turbopack/internal-error.js:38:17) {
  location: undefined
}
destroyed next instance: 7.653ms

Now we report a more useful message that has some suggestions

./app/globals.css
Error: Node.js worker processes could not connect to Turbopack
Turbopack is configured to run webpack loaders and PostCSS transforms in child processes that communicate with it over a loopback TCP connection, but the child process was unable to connect while evaluating loaders [postcss]:
connect ENETUNREACH 127.0.0.1
This is likely caused by a sandbox or firewall that blocks connections. Allow local connections, or run this code using worker threads by setting `experimental.turbopackPluginRuntimeStrategy: 'workerThreads'` in your Next.js config.

https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopackPluginRuntimeStrategy

[github-actions]

Failing CI jobs

Commit: 31f5ac0 | About building and testing Next.js

• test next-swc wasi / build