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 bundleCLAUDE_CODE_STARTUP_FAILURE_RESULTS
Documented inclaude-code/agent-sdk/typescript
One source agreesOne thing we can check says the same as this entry.
The name it cites is new in this build
New in this build: CLAUDE_CODE_STARTUP_FAILURE_RESULTS