Turbopack Build Panic Misattributes NUL-Byte Env Error To CSS Module
On Windows, a malformed inherited environment variable containing a NUL byte causes Turbopack to fail with a panic that incorrectly points to an unrelated CSS module, hiding the actionable environment variable name.
Turbopack spawns pooled Node processes and passes the full process environment to child_process.spawn. Node rejects environment values containing NUL bytes, but the error is wrapped by Turbopack's error handling and misattributed to the CSS processing task that triggered the spawn.
1. Set an environment variable with a NUL byte (e.g., steam_master_ipc_name_override=Remote\x00).
2. Run 'node node_modules/next/dist/bin/next build --turbo'.
3. Observe the TurbopackInternalError pointing to app/globals.css and 'nul byte found in provided data'.
4. Compare with 'node node_modules/next/dist/bin/next build --webpack' which correctly reports the offending variable name.
Fixing Code Block
// Insert this code at the top of the Next.js build entry point (e.g., packages/next/src/build/index.ts)
// It validates that no environment variable has a NUL byte, which would cause child_process.spawn to fail.
function validateEnvironmentVariables() {
for (const [key, value] of Object.entries(process.env)) {
if (typeof value === 'string' && value.includes('\0')) {
throw new TypeError(
`The property 'options.env['${key}']' must be a string without null bytes. Received '${value}'`
);
}
}
}
// Call this function at the start of the build process, before any child processes are spawned.
validateEnvironmentVariables();
This hotfix adds an early validation loop over process.env to detect NUL bytes before any child process is spawned. It throws a descriptive TypeError with the exact environment variable name, mirroring the Webpack error style. By failing early in the Node layer, we prevent the error from being wrapped by Turbopack's Rust error handling and misattributed to the CSS module.
Edge Case Audit
The patch may cause the build to fail earlier than before (at the start) even if the malformed environment variable would never be used by a spawned process. This is acceptable because any child_process.spawn with a NUL-containing env will fail anyway. Rollback: remove the validation function if it causes false positives (e.g., if some environment variables are intentionally stripped before spawn). Also, this fix only covers the Node-side spawn path; if Turbopack's Rust code spawns processes directly without going through Node's spawn, the underlying error may persist, but the primary Node pooled process path is covered.
