{"version":"2.1.274","anchor":"headlessstream-json-errors-gain-a-structured-startupfailure","canonical_anchor":"headlessstream-json-errors-gain-a-structured-startupfailure","heading":"Headless\/stream-json errors gain a structured startupFailureReason field","tier":"internal","area":"Headless Mode","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.274\/e\/headlessstream-json-errors-gain-a-structured-startupfailure","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.274","markdown":"### Headless\/stream-json errors gain a structured startupFailureReason field\n\nHeadless mode's startup-failure errors now include a structured reason code\n\n**What**\n\nWhen Claude Code fails to start in headless mode (running without an interactive interface, using stream-json output), the error-reporting helper now accepts a `startupFailureReason` and a `resultIndex`, and includes both in the emitted stream-json error object. One concrete reason value is `session_held_by_background`, used when a session is already held by a background process.\n\n**Why**\n\nThis gives tools and scripts consuming stream-json output a structured way to detect and handle specific headless startup failures, such as a session being locked by another background process, instead of just seeing a generic error.\n\n- Area: Headless Mode\n- Tier: Under the hood\n- Useful: 2\/5\n- Signal: 2\/5"}