Skip to main content
Entries on this page are keyed to the error you see. Each names the cause and what to do.

​
CLI startup

​
CLINotFoundError: Claude Code not found

The Python SDK launches the Claude Code CLI as a subprocess. When it can’t find a claude executable, connecting fails with a CLINotFoundError:
The message includes the configured path when you set ClaudeAgentOptions(cli_path=...) and it points at a missing file. Without cli_path, the SDK searches your PATH and common install locations, and the message includes install instructions for your platform. To fix it:
  • Install Claude Code if it isn’t installed. See Install Claude Code for the command on your platform.
  • If you set cli_path, confirm the file exists and is the claude executable.
  • 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.

​
CLIConnectionError: Refusing to execute batch script

On 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:
The refusal is deliberate security hardening, not a broken install. Windows runs batch scripts by rewriting the spawn into a cmd.exe /c invocation, and cmd.exe re-parses the whole command line at execution time, so an argument value can execute injected commands. Most Windows installs never reach this error. The Windows x64 wheel of claude-agent-sdk bundles a claude.exe, and the SDK prefers the bundled CLI, then any native claude.exe it can discover, before falling back to a batch shim. You see the refusal in two cases:
  • You set ClaudeAgentOptions(cli_path=...) to a .bat or .cmd file, such as npm’s claude.cmd shim.
  • Your install has no bundled or native claude.exe, for example a source install on ARM64 Windows where the only claude on your PATH is the npm shim.
To fix it, give the SDK a native executable instead of a batch script:
  • If you set ClaudeAgentOptions(cli_path=...), point it at a claude.exe or remove the option. The SDK skips discovery while cli_path is set, so a native install alone can’t take effect.
  • Install Claude Code natively in PowerShell: irm https://claude.ai/install.ps1 | iex
  • On x64 Windows, install the claude-agent-sdk wheel, which bundles claude.exe.
Before claude-agent-sdk 0.2.124, the Python SDK spawned batch scripts through cmd.exe without this check.

​
Structured outputs

​
structured_output is None but the result says success

A 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. One way to hit this is a schema no output can satisfy, for example conflicting length constraints. The run ends without a validation error, and the only signal is the missing structured_output. Treat 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 section shows this pattern for both SDKs. If it happens repeatedly with a schema you believe is correct, verify the schema is satisfiable, then simplify it until outputs validate, and reintroduce constraints one at a time.

​
Report a new issue

If your error isn’t covered here, check the open issues or file a new one in the SDK repositories: claude-agent-sdk-typescript or claude-agent-sdk-python. Include the full error text and your SDK version.