Sweep 19 Sep 2026 · 02:36Z Build v2.1.278 500 read Stable v2.1.267 Latest v2.1.278 Next v2.1.278 Feeds RSS JSON llms.txt Unofficial
Claude Code v2.1.274 ·

Startup failures are now reported as structured JSON in stream-json/SDK mode

CLI startup failures can now be reported as structured JSON results for SDK and programmatic callers, not just printed to stderr

TierUse it nowhow much it should matter to you
Useful2my rating, 1 to 5
Signal1worth watching, 1 to 5
AreaSDKwhat it touches
KindNew Featuresin v2.1.274,
Group of 5 Use it now

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 structured result message 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_reason field, with values seen including cli_version_too_old, shell_tool_missing, proxy_invalid, and session_held_by_background.
  • This behavior requires both --output-format stream-json and the environment variable CLAUDE_CODE_STARTUP_FAILURE_RESULTS to 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.

Read from
Names in the bundleCLAUDE_CODE_STARTUP_FAILURE_RESULTS
What the documentation says
How sure we are
One source agreesOne thing we can check says the same as this entry.
The name it cites is new in this buildNew in this build: CLAUDE_CODE_STARTUP_FAILURE_RESULTS

See this entry in the whole of v2.1.274 →