### CLIConnectionError: Failed to start Claude Code ### CLIConnectionError: Not connected ## CLI process exit ### ProcessError: Command failed with exit code ### Claude Code process exited with code N ### Claude Code returned an error result
The whole hunk
from line 22, old and new numbered
/
lines
from line 22
2222* If you set `cli_path`, confirm the file exists and is the `claude` executable.
2323* If you rely on `PATH` resolution, confirm `claude --version` works in the same environment your application runs in. Processes you launch outside your shell, such as from an IDE or a service manager, often run with a different `PATH`.
2424
25The TypeScript SDK reports a missing executable as `Claude Code native binary not found at <path>` or `Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?`. It looks for the CLI in only two places, its bundled platform package and the path you set in `pathToClaudeCodeExecutable`. Reinstall `@anthropic-ai/claude-agent-sdk` without skipping optional dependencies so the bundled binary is present, or point `pathToClaudeCodeExecutable` at a [native install](/docs/en/setup#install-claude-code).
26
2527### CLIConnectionError: Refusing to execute batch script
2628
2729On Windows, connecting fails with a `CLIConnectionError` when the CLI path the Python SDK uses is a `.bat` or `.cmd` batch script, including the `claude.cmd` shim that an npm install creates:
from line 46
4446* On x64 Windows, install the `claude-agent-sdk` wheel, which bundles `claude.exe`.
4547
4648Before `claude-agent-sdk` 0.2.124, the Python SDK spawned batch scripts through `cmd.exe` without this check.
49
50### CLIConnectionError: Failed to start Claude Code
51
52The SDK found a file at the configured path but couldn't launch it. Python raises these failures as a `CLIConnectionError`. TypeScript rejects the message iteration with an error carrying no SDK class. The table below maps each message to what it tells you. Match the message you see:
53
54| Message | SDK | What it tells you |
55| ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
56| `Failed to start Claude Code: <detail>` | Python | The rest of the message is the operating system's own error |
57| `Claude Code executable at <path> exists but failed to launch` | TypeScript | The script at the configured path can't run |
58| `Claude Code native binary at <path> exists but failed to launch` | TypeScript | The binary can't run, with a libc suggestion appended to the message |
59| `Failed to spawn Claude Code process: <detail>` | TypeScript | Any other launch failure |
60
61In both SDKs, the usual cause is a configured path that points at something that can't run, such as a text file, a directory, or a file without execute permission. Read the native-binary message's libc suggestion as one possible cause.
62
63To fix it in either SDK:
64
65* Confirm the configured path points at the `claude` executable itself and that the file has execute permission.
66* If you don't need a custom path, remove `cli_path` in Python or `pathToClaudeCodeExecutable` in TypeScript so the SDK finds a CLI on its own, preferring its bundled copy.
67
68### CLIConnectionError: Not connected
69
70Calling a `ClaudeSDKClient` method in Python before the client has connected, or after it has disconnected, raises a `CLIConnectionError` with this message:
71
72```
73Not connected. Call connect() first.
74```
75
76Do what the message says. Either call `await client.connect()` before any other client method, or open the client with `async with ClaudeSDKClient() as client:`, which connects on entry.
77
78## CLI process exit
79
80The entries in this section mean the Claude Code process ended while your application was using it. Which error you see depends on the SDK language and on whether the CLI reported an error result before it exited.
81
82### ProcessError: Command failed with exit code
83
84The Python SDK raises a `ProcessError` when the Claude Code process exits with a nonzero code:
85
86```
87Command failed with exit code 1 (exit code: 1)
88Error output: Check stderr output for details
89```
90
91The message states the exit code twice, and the `Error output` line is fixed text rather than your process's error output. The same fixed text fills the exception's `stderr` attribute. The exception's `exit_code` attribute carries the code. To capture what the CLI actually wrote to stderr, pass a `stderr` callback in `ClaudeAgentOptions` and log what it receives.
92
93A bare `ProcessError` means the CLI exited without reporting an error result. When the CLI did report one, the SDK raises [`ResultError`](/docs/en/agent-sdk/python#resulterror) instead, covered in [Claude Code returned an error result](#claude-code-returned-an-error-result). `ResultError` subclasses `ProcessError`, so `except ProcessError` catches both. To handle them differently, put the `except ResultError` clause first.
94
95Before `claude-agent-sdk` 0.2.140, the Python SDK raised error-result exits as a plain `Exception` rather than a `ResultError`.
96
97### Claude Code process exited with code N
98
99IDE wrappers print this message too, and the [error reference](/docs/en/errors#claude-code-process-exited-with-code-n) covers it for VS Code and other launchers. This entry covers what your TypeScript SDK code receives. The SDK surfaces a nonzero CLI exit as a plain `Error` that rejects the `for await` loop over `query()`'s messages. There's no SDK error class to catch, so wrap the loop in `try`/`catch` and match on the message:
100
101```
102Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>
103```
104
105When the CLI wrote to stderr, the message ends with the tail of it. To capture the full stream, pass a `stderr` callback in the query options. A process killed by a signal reports `Claude Code process terminated by signal <name>` in the same form.
106
107### Claude Code returned an error result
108
109Both SDKs replace the process-exit error with this message when the CLI reported an error result before exiting:
110
111```
112Claude Code returned an error result: <the CLI's own error report>
113```
114
115The text after the colon is the CLI's report of what went wrong, so start there rather than with the exit itself. Python raises this as a [`ResultError`](/docs/en/agent-sdk/python#resulterror), whose `data` attribute carries the full error result. TypeScript rejects the message loop with a plain `Error` carrying the same message shape.
47116
48117## Structured outputs
49118