Troubleshoot the Agent SDK changedagent-sdk/troubleshooting
Nearest release: v2.1.305, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 18:25 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+15added
Lines−15removed
From line
8
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits11to this page, all time
The whole hunk
from line 8, old and new numbered
/
from line 8
88
99| Symptom | Go to |
1010| :- | :- |
11| Skills not found, a skill not being used, `Invalid skill name` error | [Skills troubleshooting](/docs/en/agent-sdk/skills.md#troubleshooting) |
12| MCP server shows `failed` status, tools not being called, a tool missing from an SDK MCP server, connection timeouts, tool output that exceeds the maximum allowed tokens | [MCP troubleshooting](/docs/en/agent-sdk/mcp.md#troubleshooting) |
13| Plugin not loading, plugin skills not appearing | [Plugins troubleshooting](/docs/en/agent-sdk/plugins.md#troubleshooting) |
14| Claude not delegating to subagents, filesystem-based agents not loading | [Subagents troubleshooting](/docs/en/agent-sdk/subagents.md#troubleshooting) |
15| Checkpointing options not recognized, user messages without UUIDs, `No file checkpoint found`, `File rewinding is not enabled`, `ProcessTransport is not ready for writing` | [File checkpointing troubleshooting](/docs/en/agent-sdk/file-checkpointing.md#troubleshooting) |
16| Hook not firing, matcher not filtering as expected, hook timeout, tool blocked unexpectedly, modified input not applied, session hooks not available in Python, subagent permission prompts multiplying, recursive hook loops with subagents, `systemMessage` not appearing in output | [Fix common issues](/docs/en/agent-sdk/hooks.md#fix-common-issues) on the hooks page |
17| An agent that works on your machine fails in a deployed service or container | [Troubleshoot deployment failures](/docs/en/agent-sdk/hosting.md#troubleshoot-deployment-failures) |
18| `Not logged in`, `Invalid API key`, `API Error`, `429`, `There's an issue with the selected model` | [Error reference](/docs/en/errors.md#find-your-error) |
11| Skills not found, a skill not being used, `Invalid skill name` error | [Skills troubleshooting](https://code.claude.com/docs/en/agent-sdk/skills.md#troubleshooting) |
12| MCP server shows `failed` status, tools not being called, a tool missing from an SDK MCP server, connection timeouts, tool output that exceeds the maximum allowed tokens | [MCP troubleshooting](https://code.claude.com/docs/en/agent-sdk/mcp.md#troubleshooting) |
13| Plugin not loading, plugin skills not appearing | [Plugins troubleshooting](https://code.claude.com/docs/en/agent-sdk/plugins.md#troubleshooting) |
14| Claude not delegating to subagents, filesystem-based agents not loading | [Subagents troubleshooting](https://code.claude.com/docs/en/agent-sdk/subagents.md#troubleshooting) |
15| Checkpointing options not recognized, user messages without UUIDs, `No file checkpoint found`, `File rewinding is not enabled`, `ProcessTransport is not ready for writing` | [File checkpointing troubleshooting](https://code.claude.com/docs/en/agent-sdk/file-checkpointing.md#troubleshooting) |
16| Hook not firing, matcher not filtering as expected, hook timeout, tool blocked unexpectedly, modified input not applied, session hooks not available in Python, subagent permission prompts multiplying, recursive hook loops with subagents, `systemMessage` not appearing in output | [Fix common issues](https://code.claude.com/docs/en/agent-sdk/hooks.md#fix-common-issues) on the hooks page |
17| An agent that works on your machine fails in a deployed service or container | [Troubleshoot deployment failures](https://code.claude.com/docs/en/agent-sdk/hosting.md#troubleshoot-deployment-failures) |
18| `Not logged in`, `Invalid API key`, `API Error`, `429`, `There's an issue with the selected model` | [Error reference](https://code.claude.com/docs/en/errors.md#find-your-error) |
1919| `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `Claude Code process exited with code N`, `Claude Code returned an error result`, `structured_output` is `None` | [CLI startup](#cli-startup), [CLI process exit](#cli-process-exit), and [Structured outputs](#structured-outputs) on this page |
2020
2121## CLI startup
from line 32
3232
3333To fix it:
3434
35* Install Claude Code if it isn't installed. See [Install Claude Code](/docs/en/setup.md#install-claude-code) for the command on your platform.
35* Install Claude Code if it isn't installed. See [Install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code) for the command on your platform.
3636* If you set `cli_path`, confirm the file exists and is the `claude` executable.
3737* 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`.
3838
3939The TypeScript SDK looks for the CLI in its bundled platform package and the path you set in `pathToClaudeCodeExecutable`. Match the message you see:
4040
41* `Native CLI binary for <platform>-<arch> not found`: the bundled platform package is missing, most often because the install skipped optional dependencies. Reinstall `@anthropic-ai/claude-agent-sdk` without skipping optional dependencies, or point `pathToClaudeCodeExecutable` at a [native install](/docs/en/setup.md#install-claude-code). In a single-file executable built with `bun build --compile`, the same message has a different cause and fix. See [Compile to a single executable](/docs/en/agent-sdk/typescript.md#compile-to-a-single-executable).
41* `Native CLI binary for <platform>-<arch> not found`: the bundled platform package is missing, most often because the install skipped optional dependencies. Reinstall `@anthropic-ai/claude-agent-sdk` without skipping optional dependencies, or point `pathToClaudeCodeExecutable` at a [native install](https://code.claude.com/docs/en/setup.md#install-claude-code). In a single-file executable built with `bun build --compile`, the same message has a different cause and fix. See [Compile to a single executable](https://code.claude.com/docs/en/agent-sdk/typescript.md#compile-to-a-single-executable).
4242* `Claude Code native binary not found at <path>` or `Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?`: the file at the resolved path is missing, or the process can't access it. Confirm the file exists at that path and that the process can access it.
4343
4444### CLIConnectionError: Refusing to execute batch script
from line 108
108108
109109The 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.
110110
111A 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.
111A bare `ProcessError` means the CLI exited without reporting an error result. When the CLI did report one, the SDK raises [`ResultError`](https://code.claude.com/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.
112112
113113Before `claude-agent-sdk` 0.2.140, the Python SDK raised error-result exits as a plain `Exception` rather than a `ResultError`.
114114
115115### Claude Code process exited with code N
116116
117IDE wrappers print this message too, and the [error reference](/docs/en/errors.md#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:
117IDE wrappers print this message too, and the [error reference](https://code.claude.com/docs/en/errors.md#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:
118118
119119```
120120Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>
from line 130
130130Claude Code returned an error result: <the CLI's own error report>
131131```
132132
133The 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.
133The 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`](https://code.claude.com/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.
134134
135135## Structured outputs
136136
from line 138
138138
139139A result message can end with `subtype: "success"` while `structured_output` is `None` in Python or `undefined` in TypeScript. The run completes, but no validated output exists.
140140
141Treat this result as a failure in application code. Check both that `subtype` is `success` and that `structured_output` is present before using it. The [Error handling](/docs/en/agent-sdk/structured-outputs.md#error-handling) section shows this pattern for both SDKs. Then check for these causes:
141Treat this result as a failure in application code. Check both that `subtype` is `success` and that `structured_output` is present before using it. The [Error handling](https://code.claude.com/docs/en/agent-sdk/structured-outputs.md#error-handling) section shows this pattern for both SDKs. Then check for these causes:
142142
143* **A request that Claude declined**: to detect this case in your code, check the result message's `stop_reason` for `"refusal"`. For what to try next, see [Usage Policy refusal](/docs/en/errors.md#usage-policy-refusal).
143* **A request that Claude declined**: to detect this case in your code, check the result message's `stop_reason` for `"refusal"`. For what to try next, see [Usage Policy refusal](https://code.claude.com/docs/en/errors.md#usage-policy-refusal).
144144* **A schema no output can satisfy**: for example, a string whose `minLength` is greater than its `maxLength`. If `structured_output` is missing repeatedly with a schema you believe is correct, look for constraints that contradict each other. If you find none, simplify the schema until outputs validate, then reintroduce your constraints one at a time.
145145
146146## Report a new issue
No line in this hunk matches that.