Skip to main content
このページのエントリは、表示されるエラーに対応しています。各エントリは原因と対処方法を示しています。

​
CLI スタートアップ

​
CLINotFoundError: Claude Code not found

Python SDK は Claude Code CLI をサブプロセスとして起動します。claude 実行ファイルが見つからない場合、接続は CLINotFoundError で失敗します。
メッセージには、ClaudeAgentOptions(cli_path=...) を設定して存在しないファイルを指している場合、設定されたパスが含まれます。cli_path がない場合、SDK は PATH と一般的なインストール場所を検索し、メッセージにはプラットフォーム用のインストール手順が含まれます。 修正するには：
  • Claude Code がインストールされていない場合はインストールしてください。プラットフォーム用のコマンドについては、Claude Code のインストールを参照してください。
  • cli_path を設定した場合は、ファイルが存在し、claude 実行ファイルであることを確認してください。
  • PATH 解決に依存している場合は、アプリケーションが実行される環境で claude --version が機能することを確認してください。IDE やサービスマネージャーなど、シェルの外から起動するプロセスは、多くの場合異なる PATH で実行されます。
TypeScript SDK は、バンドルされたプラットフォームパッケージと pathToClaudeCodeExecutable に設定されたパスで CLI を探します。表示されるメッセージに一致させてください：
  • Native CLI binary for <platform>-<arch> not found：バンドルされたプラットフォームパッケージが見つかりません。最も一般的には、インストールがオプション依存関係をスキップしたためです。オプション依存関係をスキップせずに @anthropic-ai/claude-agent-sdk を再インストールするか、pathToClaudeCodeExecutable をネイティブインストールに指定してください。bun build --compile で構築された単一ファイル実行ファイルでは、同じメッセージが異なる原因と修正方法を持ちます。単一実行ファイルへのコンパイルを参照してください。
  • Claude Code native binary not found at <path> または Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?：解決されたパスのファイルが見つからないか、プロセスがアクセスできません。ファイルがそのパスに存在し、プロセスがアクセスできることを確認してください。

​
CLIConnectionError: Refusing to execute batch script

Windows では、Python SDK が使用する CLI パスが .bat または .cmd バッチスクリプト（npm インストールが作成する claude.cmd シムを含む）の場合、接続は CLIConnectionError で失敗します。
この拒否は意図的なセキュリティ強化であり、インストールが壊れているわけではありません。Windows はバッチスクリプトを cmd.exe /c 呼び出しに書き換えて実行し、cmd.exe は実行時にコマンドライン全体を再解析するため、引数値は注入されたコマンドを実行できます。 ほとんどの Windows インストールはこのエラーに到達しません。Windows x64 の claude-agent-sdk ホイールは claude.exe をバンドルしており、SDK はバンドルされた CLI を優先し、次に発見できるネイティブ claude.exe を優先し、その後バッチシムにフォールバックします。拒否は 2 つのケースで表示されます：
  • ClaudeAgentOptions(cli_path=...) を .bat または .cmd ファイル（npm の claude.cmd シムなど）に設定した場合。
  • インストールにバンドルされたネイティブ claude.exe がない場合。たとえば、ARM64 Windows でのソースインストールで、PATH 上の唯一の claude が npm シムである場合。
修正するには、バッチスクリプトの代わりにネイティブ実行ファイルを SDK に提供してください：
  • ClaudeAgentOptions(cli_path=...) を設定した場合は、claude.exe を指すか、オプションを削除してください。cli_path が設定されている間、SDK は検出をスキップするため、ネイティブインストールだけでは効果がありません。
  • PowerShell で Claude Code をネイティブにインストールしてください：irm https://claude.ai/install.ps1 | iex
  • x64 Windows では、claude.exe をバンドルする claude-agent-sdk ホイールをインストールしてください。
claude-agent-sdk 0.2.124 より前では、Python SDK はこのチェックなしで cmd.exe を通じてバッチスクリプトを生成していました。

​
CLIConnectionError: Failed to start Claude Code

SDK は解決されたパスでファイルを見つけましたが、起動できませんでした。Python はこれらの失敗を CLIConnectionError として発生させます。TypeScript はメッセージ反復を SDK クラスを持たないエラーで拒否します。以下の表は各メッセージを何を示しているかにマップします。表示されるメッセージに一致させてください： 両方の SDK では、通常の原因は、テキストファイル、ディレクトリ、または実行権限のないファイルなど、実行できないものを指す解決されたパスです。ネイティブバイナリメッセージの libc 提案を 1 つの可能な原因として読んでください。 どちらの SDK でも修正するには：
  • 設定されたパスが claude 実行ファイル自体を指し、ファイルに実行権限があることを確認してください。
  • カスタムパスが不要な場合は、Python で cli_path を削除するか、TypeScript で pathToClaudeCodeExecutable を削除して、SDK が独自に CLI を見つけるようにしてください。バンドルされたコピーを優先します。
  • 失敗しているバイナリがコンテナイメージ内の SDK のバンドルされたコピーの場合、イメージビルド中に SDK を再インストールして、バンドルされたバイナリがコンテナのプラットフォームと一致するようにするか、実行するアーキテクチャ用にイメージを再構築してください。通常の原因は、コンテナのアーキテクチャまたは libc と一致しないバイナリ、またはイメージビルド中に実行権限を失ったバイナリです。

​
CLIConnectionError: Not connected

Python で ClaudeSDKClient メソッドを呼び出す前にクライアントが接続していない場合、または接続を切断した後に呼び出すと、CLIConnectionError がこのメッセージで発生します：
メッセージが言うことをしてください。他のクライアントメソッドの前に await client.connect() を呼び出すか、async with ClaudeSDKClient() as client: でクライアントを開いてください。これは入口で接続します。

​
CLI プロセス終了

このセクションのエントリは、アプリケーションがそれを使用している間に Claude Code プロセスが終了したことを意味します。表示されるエラーは SDK 言語と、CLI が終了する前にエラー結果を報告したかどうかによって異なります。

​
ProcessError: Command failed with exit code

Python SDK は Claude Code プロセスが 0 以外のコードで終了すると ProcessError を発生させます：
メッセージは終了コードを 2 回述べ、Error output 行は固定テキストであり、プロセスの実際のエラー出力ではありません。同じ固定テキストが例外の stderr 属性を埋めます。例外の exit_code 属性がコードを持ちます。CLI が実際に stderr に書き込んだものをキャプチャするには、ClaudeAgentOptions で stderr コールバックを渡し、受け取ったものをログしてください。 単純な ProcessError は、CLI がエラー結果を報告せずに終了したことを意味します。CLI がエラー結果を報告した場合、SDK は代わりに ResultError を発生させます。これはClaude Code returned an error resultで説明されています。ResultError は ProcessError をサブクラス化するため、except ProcessError は両方をキャッチします。異なる方法で処理するには、except ResultError 句を最初に配置してください。 claude-agent-sdk 0.2.140 より前では、Python SDK はエラー結果の終了を ResultError ではなく単純な Exception として発生させていました。

​
Claude Code process exited with code N

IDE ラッパーもこのメッセージを出力し、エラーリファレンスは VS Code およびその他のランチャーをカバーしています。このエントリは TypeScript SDK コードが受け取るものをカバーしています。SDK は 0 以外の CLI 終了を単純な Error として表示し、query() のメッセージ上の for await ループを拒否します。キャッチする SDK エラークラスはないため、ループを try/catch でラップし、メッセージで一致させてください：
CLI が stderr に書き込んだ場合、メッセージはそれのテールで終わります。完全なストリームをキャプチャするには、クエリオプションで stderr コールバックを渡してください。シグナルで強制終了されたプロセスは同じ形式で Claude Code process terminated by signal <name> を報告します。

​
Claude Code returned an error result

両方の SDK は、CLI が終了する前にエラー結果を報告した場合、プロセス終了エラーをこのメッセージに置き換えます：
コロンの後のテキストは、何が間違ったかについての CLI の報告であるため、終了自体ではなくそこから始めてください。Python はこれを ResultError として発生させます。その data 属性は完全なエラー結果を持ちます。TypeScript は同じメッセージ形式を持つ単純な Error でメッセージループを拒否します。

​
構造化出力

​
structured_output は None ですが、結果は成功と言っています

結果メッセージは subtype: "success" で終わることができますが、Python では structured_output は None であり、TypeScript では undefined です。実行は完了しますが、検証された出力は存在しません。これに到達する 1 つの方法は、出力が満たすことができないスキーマです。たとえば、矛盾する長さの制約があります。実行は検証エラーなしで終了し、唯一の信号は欠落している structured_output です。 アプリケーションコードでこの結果を失敗として扱ってください。structured_output を使用する前に、subtype が success であり、structured_output が存在することの両方を確認してください。エラーハンドリングセクションは両方の SDK のこのパターンを示しています。 正しいと思われるスキーマで繰り返し発生する場合は、スキーマが満たされることを確認し、出力が検証されるまで単純化し、制約を 1 つずつ再導入してください。

​
新しい問題を報告する

エラーがここでカバーされていない場合は、オープンな問題を確認するか、SDK リポジトリに新しい問題を提出してください：claude-agent-sdk-typescript または claude-agent-sdk-python。完全なエラーテキストと SDK バージョンを含めてください。