マルチエージェントAgent SDK のエラー対処｜起動しない・止まる時
この記事の要点
- エラーは表示の名前で引く。起動の失敗（CLINotFoundError・CLIConnectionError）、途中の終了（ProcessError など）、出力の失敗の3つに分かれる
- 起動しない時は、Claude Code の本体が見つかるか・実行できるかを確かめる。場所を自分で指定しているなら、その指定を外すのが近道
- success なのに決めた形の出力が空の時は、失敗として扱い、断られたか・形の条件が矛盾していないかを見る
活用例：社内のサーバーで動かしている AI エージェントが止まった時の一次対応
- 部署
- 情報システム・開発
- 使うもの
- Claude Agent SDK
- AIに任せる
- エラーの表示からの原因の当たり付けと、確かめる手順の提示
- 人が決める
- 直す範囲・再実行するか・本体の入れ直しをするか
Claude Agent SDK で作った AI エージェントが 「起動しない」「途中で止まる」「成功と出たのに中身が空」 という時は、表示されたエラーの名前から原因を引くのがいちばん速い方法です。
この記事では、公式ドキュメント「Troubleshoot the Agent SDK」（2026年11月12日確認）にもとづいて、エラーの表示ごとに原因と直し方を整理します。SDK の全体像は Claude Agent SDK とは で解説しています。
結論：エラーは「起動」「途中の終了」「出力」の3つに分けて見る
Agent SDK は、裏で Claude Code の本体を動かしています。 そのため、エラーの多くは「本体を起動できない」「本体が途中で終わった」「本体は終わったが決めた形の出力が無い」のどれかです。まずどれに当たるかを見分けます。
まず全体の早見表
| 表示 | 分類 | まず見ること |
|---|---|---|
| CLINotFoundError | 起動 | 本体が入っているか・場所の指定 |
| CLIConnectionError: Refusing to execute batch script | 起動（Windows） | .cmd や .bat を指していないか |
| CLIConnectionError: Failed to start Claude Code | 起動 | 指した先が実行できるファイルか |
| CLIConnectionError: Not connected | 起動（Python） | 接続する前に呼んでいないか |
| ProcessError: Command failed with exit code | 途中の終了（Python） | 本体が書いたエラー出力 |
| Claude Code process exited with code N | 途中の終了（TypeScript） | 同上 |
| Claude Code returned an error result | 途中の終了 | コロンの後ろの本文 |
| success なのに structured_output が空 | 出力 | 断られていないか・形の条件 |
スキル・MCP・フックなど、機能ごとの困りごとは、それぞれの機能のページに対処がまとまっています。
起動しない時
本体が見つからない（CLINotFoundError）
Python の SDK が、Claude Code の本体を見つけられない時のエラーです。 次の順に確かめます。
- Claude Code の本体が入っているか
- 場所を自分で指定（cli_path）しているなら、そこに本当にファイルがあるか
- 指定していないなら、アプリを動かすのと同じ環境で claude --version が動くか
3つ目が見落としやすい点です。エディタやサービスの仕組みから起動したプログラムは、ふだんのシェルと違う道（PATH）で動いていることがよくあります。
TypeScript の SDK では、本体は同梱の部品から探します。「Native CLI binary for ... not found」と出たら、入れる時に任意の部品を飛ばしていないかを見て、SDK を入れ直します。
Windows でバッチのファイルを断られる
npm で入れた時にできる claude.cmd のようなバッチのファイルは、安全のためにわざと断られます。 壊れているのではありません。バッチのファイルは、渡した文字の中身によって別の命令を実行されてしまうおそれがあるためです。
直し方は、場所の指定（cli_path）を外すか、実行ファイル（claude.exe）を指すようにすることです。公式のインストーラーで Claude Code を入れる方法もあります。
見つかったのに起動できない
指した先が、テキストのファイル・フォルダ・実行の権限が無いファイルになっていることが多いです。自分で場所を指定する必要が無いなら、指定を外すと SDK が同梱の本体を自分で探します。 コンテナの中で動かしている時は、本体がコンテナの種類（CPU や部品）に合っていないことがあるので、イメージを作る時に SDK を入れ直します。
途中で終わった時
本体が途中で終わった時は、エラーの文より、本体が書いたエラー出力を見るのが近道です。 Python の ProcessError に出る「Error output」の行は決まった文で、本当の出力ではありません。本当の出力を見たい時は、設定に stderr を受け取る関数を渡して記録します。
「Claude Code returned an error result」と出た時は、コロンの後ろが本体からの報告 なので、そこから読みます。Python では ResultError として届き、中に結果の全体が入っています。
成功なのに出力が空の時
結果が success なのに、決めた形の出力（structured_output）が空のことがあります。 アプリの中では失敗として扱い、次の2つを確かめます。
- 断られた：結果の stop_reason が refusal になっていないか
- 条件が矛盾している：「最低10文字・最大5文字」のように、満たせない条件が入っていないか
条件が正しいはずなのに何度も空になる時は、形の条件を一度ゆるめて出力が通るのを確かめ、1つずつ条件を戻していきます。形の決め方は Agent SDK の構造化出力 で解説しています。
よくある質問
手元では動くのに、サーバーに置くと動きません
起動の道（PATH）・本体の有無・環境変数が手元と違うことが多いです。置く場所ごとの確かめ方は Agent SDK のホスティング にまとめています。
ログインや API キーのエラーはどこを見ればいいですか？
「Not logged in」「Invalid API key」や 429 などは、Claude Code 全体のエラー一覧に対処があります。Claude Code のエラー対処 を見てください。
まとめ
- エラーは 起動・途中の終了・出力 の3つに分けて引く
- 起動しない時は、同じ環境で本体が動くか と、場所の指定を確かめる
- success でも出力が空なら 失敗として扱い、断られたか・条件の矛盾を見る
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
