{"record":{"id":"cbc76ea0cb50c295","repo":"symfony/process","slug":"the-environment-block-size-d-exceeds-the-windows-limit-of-d","errorCode":null,"errorMessage":"The environment block size (%d) exceeds the Windows limit of %d UTF-16 code units.","messagePattern":"The environment block size \\((.+?)\\) exceeds the Windows limit of (.+?) UTF-16 code units\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"Process.php","lineNumber":1757,"sourceCode":"                    'SERVER_PROTOCOL', 'SERVER_SIGNATURE', 'SERVER_SOFTWARE',\n                ], true)\n            ) {\n                unset($env[$k]);\n            }\n        }\n\n        return $env;\n    }\n\n    private function validateWindowsEnvBlockSize(array $envPairs): void\n    {\n        $block = implode(\"\\0\", $envPairs).\"\\0\";\n        @preg_replace('/./u', '', $block, -1, $blockLength)\n            ?? preg_replace('/./', '', $block, -1, $blockLength);\n        $blockLength += 1 + preg_match_all('/[\\xF0-\\xF4][\\x80-\\xBF]{3}/', $block);\n\n        if ($blockLength > self::WINDOWS_ENV_BLOCK_MAX_LENGTH) {\n            throw new InvalidArgumentException(\\sprintf('The environment block size (%d) exceeds the Windows limit of %d UTF-16 code units.', $blockLength, self::WINDOWS_ENV_BLOCK_MAX_LENGTH));\n        }\n    }\n}\n","sourceCodeStart":1739,"sourceCodeEnd":1761,"githubUrl":"https://github.com/symfony/process/blob/99b85026db14a68f02c6f3eeb01a1170ca25c491/Process.php#L1739-L1761","documentation":"Symfony Process enforces the Windows CreateProcess limit on the environment block: the environment passed to a child process must fit within a maximum number of UTF-16 code units. This library joins all env pairs into a NUL-delimited block and measures its length (accounting for 4-byte UTF-8 sequences), throwing InvalidArgumentException when it exceeds self::WINDOWS_ENV_BLOCK_MAX_LENGTH.","triggerScenarios":"Calling start() (or run(), which calls start()) on Windows with an environment containing very long or very many variables so the joined env block exceeds WINDOWS_ENV_BLOCK_MAX_LENGTH.","commonSituations":"Inheriting a huge environment (CI systems with many variables), setting very long PATH or variable values, or adding large env entries via setEnv()/setDefaults() before launching a process on Windows.","solutions":["Remove or shorten unnecessary environment variables before starting the process","Pass an explicit smaller env array via Process::setEnv() or the constructor instead of merging the full inherited environment","Split the work across multiple processes, or move large data out of env vars into files/arguments","On non-Windows systems this limit is irrelevant; gate the env reduction behind PHP_OS_FAMILY checks if needed"],"exampleFix":"// before\n$process = new Process($cmd, null, array_merge(getenv(), $hugeExtraEnv));\n$process->start();\n// after\n$env = array_intersect_key(array_merge(getenv(), $hugeExtraEnv), array_flip(['PATH', 'HOME', 'TEMP']));\n$process = new Process($cmd, null, $env);\n$process->start();","handlingStrategy":"validation","validationCode":"$pairs = [];\nforeach ($env as $k => $v) { $pairs[] = $k.'='.$v; }\n$size = strlen(implode(\"\\0\", $pairs)) + count(preg_grep('/[\\xF0-\\xF4][\\x80-\\xBF]{3}/', $pairs));\nif ($size > 32766) { $env = array_slice($env, 0, 10, true); } // trim before start()","typeGuard":null,"tryCatchPattern":"try { $process->start(); } catch (\\InvalidArgumentException $e) { if (str_contains($e->getMessage(), 'environment block size')) { $process->setEnv($trimmedEnv); $process->start(); } else { throw $e; } }","preventionTips":["Keep child env minimal: pass only required vars instead of merging the full inherited environment","Avoid storing payloads or config in environment variables on Windows","Compute env block size in CI tests for Windows-targeted jobs","Use files or arguments for large data instead of env vars"],"tags":["windows","process","environment-variables","argument-error"],"backgroundTag":"value-out-of-range","analyzedSha":"99b85026db14a68f02c6f3eeb01a1170ca25c491","analyzedAt":"2026-09-14T11:23:33.683Z","contentChangedAt":"2026-09-14T11:23:33.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}