Agent SDKのエラー集 — CLINotFoundErrorと構造化出力None

Agent SDKのエラーの切り分け方

Agent SDKのエラーは発生箇所で3種類に分かれます。CLI起動時に失敗するもの、CLIプロセスが実行中に終了するもの、そして構造化出力が検証を通らないものです。エラーメッセージの文言はPythonとTypeScriptで異なりますが、原因の分類は共通しています。

自分の環境でどれに当たるかは、まず実行形態で絞り込めます。ローカルのシェルから直接動かしている場合はCLI起動時のエラー(CLINotFoundError・Native CLI binary not found)が主に該当し、CI/コンテナ環境で動かしている場合はプロセス終了系のエラー(ProcessError・process exited with code N)が典型です。コンテナはSDKに同梱されたネイティブバイナリのアーキテクチャがホストと食い違っていることが多く、docker build 時のプラットフォーム指定を疑うと切り分けが早くなります。

npm/pipのインストール自体でつまずく場合は、Claude Codeでよくあるエラー10選のインストール関連の節が対象です。本記事はAgent SDKのライブラリ呼び出しで発生するエラーに絞ります。

CLIが見つからない・起動できないエラー

CLINotFoundError: Claude Code not found(Python)

Python SDKは内部でClaude Code CLIをサブプロセスとして起動します。claude 実行ファイルが見つからないと、次のメッセージで CLINotFoundError が発生します。

Claude Code not found at: /your/configured/path

ClaudeAgentOptions(cli_path=...) でパスを指定していて、そのファイルが存在しない場合はメッセージにそのパスが含まれます。cli_path を指定していなければSDKは PATH と一般的なインストール場所を探索し、プラットフォーム別のインストール手順もメッセージに含めます。

対処は次の3点です。

• Claude Code本体が未インストールなら先にインストールする
• cli_path を指定している場合は、そのファイルが実在し claude 実行ファイル本体であることを確認する
• PATH 解決に頼っている場合は、アプリケーションが実際に動く環境で claude --version が通るか確認する

IDEやサービスマネージャーから起動したプロセスは、シェルとは異なる PATH で動くことが多く、ここでの見落としが典型的な原因です。

Native CLI binary not found(TypeScript)

TypeScript SDKはバンドルされたプラットフォーム別パッケージと、pathToClaudeCodeExecutable で指定したパスからCLIを探します。表示されるメッセージによって原因が分かれます。

bun build --compile で単一実行ファイルにコンパイルした場合、同じメッセージでも原因が異なります。この構成では実行ファイル単体で完結させる必要があるため、通常のnpmインストールとは別の対応が要ります。

CLIConnectionError: Refusing to execute batch script(Windows)

Windowsで、Python SDKが使うCLIパスが .bat や .cmd のバッチスクリプト(npmインストールが作る claude.cmd シムを含む)を指していると、接続がこのメッセージで失敗します。

Refusing to execute batch script 'C:\Users\you\AppData\Roaming\npm\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).

この拒否は意図的なセキュリティ対策で、インストールが壊れているわけではありません。Windowsはバッチスクリプトの起動を cmd.exe /c 呼び出しに書き換えて実行し、cmd.exe は実行時にコマンドライン全体を再解析するため、引数の値経由でコマンドが注入される余地が生まれます。

ほとんどのWindows環境ではこのエラーに遭遇しません。claude-agent-sdk のWindows x64向けwheelには claude.exe が同梱されており、SDKはこの同梱CLI、次にディスク上のネイティブ claude.exe、最後にバッチシムの順で優先します。拒否が出るのは次の2ケースです。

• ClaudeAgentOptions(cli_path=...) にnpmの claude.cmd シムなど、.bat/.cmd ファイルを指定している
• ARM64 Windowsのソースインストールのように、PATH 上にnpmシム以外の claude が存在しない

cli_path を設定している間はSDKの探索自体がスキップされるため、この状態でClaude Code本体だけをネイティブ再インストールしても効果はありません。cli_path の指定を claude.exe に変更するか、指定そのものを外してSDKに探索させる必要があります。

対処はネイティブ実行ファイルを渡すことです。cli_path を指定している場合は claude.exe を指すよう変更するか、オプション自体を外してSDKに探索させます。PowerShellで irm https://claude.ai/install.ps1 | iex を実行してネイティブインストールする方法もあります。x64 Windowsでは claude-agent-sdk のwheelパッケージが claude.exe を同梱しているため、それだけで解決することもあります(ただし前述の通り cli_path を指定したままだとこの同梱バイナリは探索対象になりません)。claude-agent-sdk 0.2.124より前のPython SDKは、このチェックなしにバッチスクリプトを cmd.exe 経由で起動していました。

CLIConnectionError: Failed to start Claude Code

パス解決には成功したものの起動できない場合のエラーです。Pythonは CLIConnectionError、TypeScriptはSDKクラスを持たないプレーンな Error としてメッセージを渡します。

両SDKに共通する典型的な原因は、解決したパスがテキストファイルやディレクトリ、実行権限のないファイルなど「実行できないもの」を指している状態です。対処は次の3点です。

• 設定したパスが claude 実行ファイル自体を指し、実行権限があるか確認する
• 独自パスが不要ならオプションを外し、SDKに任せる
• コンテナイメージ内でSDKに同梱されたバイナリが失敗する場合は、イメージビルド時にSDKを再インストールしてコンテナのアーキテクチャに合わせる

CLIConnectionError: Not connected

Pythonで ClaudeSDKClient のメソッドを、接続前または切断後に呼び出すと発生します。

Not connected. Call connect() first.

メッセージの指示通り、他のクライアントメソッドを呼ぶ前に await client.connect() を呼ぶか、async with ClaudeSDKClient() as client: の形でクライアントを開いてください。後者は開いた時点で自動的に接続します。

プロセスが途中で終了したときのエラー

このセクションのエラーは、アプリケーションがCLIプロセスを使っている最中にプロセスが終了したことを意味します。どのエラーが出るかは言語と、CLIが終了前にエラー結果を報告していたかどうかで決まります。

ProcessError: Command failed with exit code(Python)

Claude Codeプロセスが非ゼロの終了コードで終わると、Python SDKは ProcessError を発生させます。

Command failed with exit code 1 (exit code: 1)
Error output: Check stderr output for details

Error output の行は実際のプロセス出力ではなく固定文言です。例外の stderr 属性を読んでも同じ固定文言が返るだけで、実際の出力は得られません。実際にCLIがstderrへ書いた内容を取得するには、ClaudeAgentOptions に stderr コールバックを渡してログに記録してください。例外の exit_code 属性に終了コードが入ります。

CLIがエラー結果を報告せずに終了した場合は素の ProcessError に、エラー結果を報告していた場合はそのサブクラスである ResultError になります(次項)。ResultError は ProcessError のサブクラスなので except ProcessError で両方捕捉できますが、扱いを分けたい場合は except ResultError を先に書いてください。claude-agent-sdk 0.2.140より前は、エラー結果での終了もプレーンな Exception として送出していました。

Claude Code process exited with code N(TypeScript)

このメッセージ自体はIDE統合でも表示されますが、本節はAgent SDKのコードが受け取る形を扱います。TypeScript SDKは非ゼロ終了を素の Error として、query() のメッセージを回す for await ループを拒否(reject)する形で伝えます。専用のSDKエラークラスは無いため、ループを try/catch で囲みメッセージを照合します。

Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

CLIがstderrに書き込んでいた場合、メッセージの末尾にその末尾部分が付きます。ストリーム全体を取得したい場合はクエリオプションに stderr コールバックを渡してください。シグナルで強制終了した場合は同じ形式で Claude Code process terminated by signal <name> と表示されます。

Claude Code returned an error result(両SDK共通)

CLIが終了前にエラー結果を報告していた場合、両SDKともプロセス終了エラーの代わりにこのメッセージになります。

Claude Code returned an error result: <the CLI's own error report>

コロン以降がCLI自身のエラー報告なので、まずそちらを確認してください。終了コード自体は手がかりになりません。Pythonはこれを ResultError として送出し、data 属性にエラー結果全体を保持します。TypeScriptは同じ内容のメッセージを持つ素の Error でメッセージループを拒否(reject)します。

構造化出力がNoneになるとき

structured_output is None but the result says success

結果メッセージが subtype: "success" で終わっているのに、Pythonでは structured_output が None、TypeScriptでは undefined のままになることがあります。実行自体は完了しますが、検証済みの出力は存在しません。原因の一例は、どんな出力でも満たせないスキーマ(長さの制約同士が矛盾しているなど)です。この場合バリデーションエラーは出ず、structured_output が欠けていることだけがシグナルになります。

アプリケーション側ではこの結果を失敗として扱ってください。subtype が success であることと structured_output が存在することの両方を確認してから使う実装が必要です。同じスキーマで繰り返し発生する場合は、スキーマが充足可能かどうかを検証し、いったん単純化してから制約を1つずつ戻していくと原因を切り分けやすくなります。

エラー早見表

この一覧に無いエラーに遭遇したら

上記に該当しないエラーは、使用しているSDKのGitHubリポジトリ(TypeScriptはclaude-agent-sdk-typescript、Pythonはclaude-agent-sdk-python)のissueを確認するか、新規に起票してください。報告時はエラーメッセージ全文とSDKのバージョンを含めると対応が早まります。

よくある質問

PythonとTypeScriptで同じエラーに同じ名前が付くか

付きません。Pythonは CLINotFoundError / CLIConnectionError / ProcessError / ResultError という専用の例外クラスを持ちますが、TypeScriptの多くはSDK固有のクラスを持たないプレーンな Error です。メッセージの文言で判別する必要があります。

エラーメッセージだけ見て対処法が分からないときは

まず本記事の早見表でエラーメッセージの断片を検索し、発生SDKと主な原因を確認してください。それでも解消しない場合は、直近のバージョンで挙動が変わっていないかAgent SDK移行ガイドのシステムプロンプトや settingSources の変更点も合わせて確認すると、エラーではなく仕様変更が原因だったケースを見つけられることがあります。

エラーの再現コードはどこにあるか

公式のサンプルやレシピはAgent SDKのサンプルと実例集にまとめています。最小構成で再現させてから調査すると、アプリケーション固有のコードが原因かSDK側かを切り分けやすくなります。

バッチスクリプト拒否は回避できるか

無効化するための公式なオプションは用意されていません。この拒否はコマンドインジェクションを防ぐための意図的な設計であり、リジェクト自体を回避する設定はSDK側にありません。素の claude.exe を使う構成に変更するのが、この状況での唯一の対処になります。

まとめ

Agent SDKのエラーはCLI起動時・プロセス終了時・構造化出力の3系統に分かれ、Pythonは専用の例外クラス、TypeScriptはメッセージ文言での判別が基本です。CLINotFoundErrorとNative CLI binary not foundはインストールとパス設定、Refusing to execute batch scriptはWindows特有のセキュリティ設計、ProcessError系は stderr コールバックでの追加情報取得が対処の起点になります。原因の見当がつかない場合は、エラーメッセージ全文とSDKのバージョンを添えて公式issueで報告してください。