{"version":"2.1.274","anchor":"startup-failures-now-reported-to-stdout-as-an-sdk-stream-jso","canonical_anchor":"startup-failure-result-payload-gated-behind-claude-code-star","heading":"Startup failures are now reported as structured JSON in stream-json\/SDK mode","tier":"use","area":"SDK","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.274\/e\/startup-failures-now-reported-to-stdout-as-an-sdk-stream-jso","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.274","markdown":"### Startup failures are now reported as structured JSON in stream-json\/SDK mode\n\nCLI startup failures can now be reported as structured JSON results for SDK and programmatic callers, not just printed to stderr\n\n**What**\n\n- 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.\n\n- 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`.\n\n- 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.\n\n**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.\n\n- Area: SDK\n- Tier: Use it now\n- Useful: 2\/5\n- Signal: 2\/5"}