turbopack: report an actionable error when Node.js child processes cannot connect (#99887)
## 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
```
<!-- NEXT_JS_LLM -->
---------
Co-authored-by:
vercel-gh-bot-3[bot] <282332853+vercel-gh-bot-3[bot]@users.noreply.github.com>
Showing
Please
register
or
sign in
to comment