Group of 5 Under the hood
No documentation found
CLI startup failures can now be reported as structured JSON results for SDK and programmatic callers, not just printed to stderr
What
- When Claude Code fails to start (for example: the CLI is too old for the workspace/server, no usable shell tool is found on Windows, proxy configuration is invalid, or another process already holds the session) and is running with
--output-format stream-json, it can now emit a structuredresultmessage on stdout carrying a machine-readable reason, in addition to (or instead of) the usual stderr text. - This reason is carried in a new
startup_failure_reasonfield, with values seen includingcli_version_too_old,shell_tool_missing,proxy_invalid, andsession_held_by_background. - This behavior requires both
--output-format stream-jsonand the environment variableCLAUDE_CODE_STARTUP_FAILURE_RESULTSto be set; the emitting function checks for the env var before doing anything.
Why This lets SDK and other programmatic callers detect exactly why a headless Claude Code process failed to start by parsing structured output, instead of having to scrape human-readable stderr text.
Names in the bundlestartupFailureReason