Agent SDK のエラー対処: CLINotFoundError と ProcessError

Claude Agent SDK は内部で Claude Code CLI をサブプロセスとして起動して動きます。そのため「CLI が見つからない」「CLI が起動できない」「CLI が途中で終了した」といった、SDK 特有のエラーに出会うことがあります。このページでは公式の「Troubleshoot the Agent SDK」に沿って、表示されたエラーメッセージごとに原因と直し方を整理します。

症状から対処ページを探す

公式のトラブルシューティングページが直接扱うのは、CLI の起動・CLI プロセスの終了・構造化出力の3種類のエラーです。フックが発火しない、スキルが使われないといった機能ごとの症状は、それぞれの機能ページのトラブルシューティング節にまとめられています。まず症状から行き先を決めます。

CLI 起動時のエラー

CLINotFoundError: Claude Code not found

Python SDK は claude 実行ファイルが見つからないと CLINotFoundError で接続に失敗します。ClaudeAgentOptions(cli_path=...) を指定していれば、その存在しないパスがメッセージに含まれます。指定していなければ SDK は PATH と一般的なインストール先を探し、メッセージにプラットフォーム別のインストール方法が出ます。

• Claude Code が未インストールならインストールする。
• cli_path を指定しているなら、そのファイルが存在し claude 実行ファイルであることを確認する。
• PATH に頼っているなら、アプリが動く環境と同じ環境で claude --version が通るか確認する。IDE やサービスマネージャーから起動したプロセスは、シェルと違う PATH で動いていることがよくあります。

TypeScript SDK は、同梱のプラットフォーム別パッケージか pathToClaudeCodeExecutable で指定したパスから CLI を探します。

• Native CLI binary for <platform>-<arch> not found: 同梱パッケージが無い状態です。多くはインストール時に optional dependencies を飛ばしたのが原因なので、飛ばさずに @anthropic-ai/claude-agent-sdk を入れ直すか、pathToClaudeCodeExecutable をネイティブインストールした claude に向けます。
• Claude Code native binary not found at <path> など: 解決したパスにファイルが無いか、プロセスからアクセスできません。

CLIConnectionError: Refusing to execute batch script（Windows）

Windows の Python SDK で、使う CLI のパスが .bat や .cmd（npm が作る claude.cmd を含む）だと、この CLIConnectionError になります。これは壊れたインストールではなく意図的なセキュリティ強化です。バッチスクリプトは cmd.exe 経由で実行され、引数に混ぜたコマンドが実行されうるうえ、確実なエスケープ方法が無いためです。

Windows x64 向けの claude-agent-sdk wheel は claude.exe を同梱しており、SDK は同梱版、次にネイティブの claude.exe を優先するので、多くの環境ではこのエラーは出ません。出るのは cli_path にバッチファイルを指定したときか、ARM64 Windows のソースインストールなど claude.exe がどこにも無いときです。直し方は次のとおりです。

• cli_path を claude.exe に向けるか、オプション自体を外す（cli_path があると自動探索をしないため、ネイティブ版を入れただけでは効きません）。
• PowerShell でネイティブ版を入れる: irm https://claude.ai/install.ps1 | iex
• x64 Windows なら claude.exe 同梱の wheel を入れる。

なお claude-agent-sdk 0.2.124 より前は、この検査なしでバッチスクリプトを起動していました。

CLIConnectionError: Failed to start Claude Code

パスにファイルはあるのに起動できなかった場合です。Python は CLIConnectionError を投げ、TypeScript は SDK 固有のクラスを持たないエラーでメッセージの反復を中断します。

よくある原因は、パスがテキストファイルやディレクトリ、実行権限の無いファイルを指していることです。指定パスが claude 本体で実行権限があるか確認し、独自パスが不要なら cli_path / pathToClaudeCodeExecutable を外して SDK に同梱版を選ばせます。コンテナイメージ内の同梱バイナリが失敗する場合は、イメージのビルド中に SDK を入れ直すか、実行するアーキテクチャ向けにイメージを作り直します（アーキテクチャや libc の不一致、ビルド中に実行権限が落ちたことが主な原因です）。

CLIConnectionError: Not connected

Python の ClaudeSDKClient のメソッドを接続前や切断後に呼ぶと Not connected. Call connect() first. になります。先に await client.connect() を呼ぶか、入るときに接続する async with で開きます。

async with ClaudeSDKClient() as client:
    await client.query("Hello")
    async for message in client.receive_response():
        print(message)

CLI プロセス終了時のエラー

この節のエラーは、アプリが使っている最中に Claude Code のプロセスが終わったことを意味します。どのエラーになるかは SDK の言語と、CLI が終了前にエラー結果を報告したかどうかで変わります。

ProcessError: Command failed with exit code（Python）

CLI が 0 以外の終了コードで終わると Python SDK は ProcessError を投げます。メッセージ中の Error output: Check stderr output for details は固定の文言で、実際の stderr ではありません（例外の stderr 属性も同じ固定文言、終了コードは exit_code 属性）。CLI が実際に stderr に書いた内容を残すには、ClaudeAgentOptions に stderr コールバックを渡してログに出します。

CLI がエラー結果を報告してから終了した場合は、ProcessError のサブクラスである ResultError になります。except ProcessError は両方を捕まえるので、分けて扱いたいときは except ResultError を先に書きます。ResultError は Python SDK 0.2.140 以降で、それ以前はプレーンな Exception でした。

from claude_agent_sdk import ClaudeAgentOptions, ProcessError, ResultError, query

options = ClaudeAgentOptions(
    stderr=lambda line: print("[claude stderr]", line),
)

try:
    async for message in query(prompt="...", options=options):
        ...
except ResultError as e:
    # CLI が報告したエラー結果（e.data に結果全体）
    print("error result:", e)
except ProcessError as e:
    # エラー結果なしでプロセスが終了した
    print("exit code:", e.exit_code)

Claude Code process exited with code N（TypeScript）

TypeScript SDK では、CLI の 0 以外の終了は query() の for await ループを中断するプレーンな Error として届きます。捕まえる専用クラスは無いので、ループを try/catch で囲みメッセージで判定します。メッセージは Claude Code process exited with code 1. stderr: <stderr の末尾> の形で、シグナルで殺された場合は Claude Code process terminated by signal <name> になります。stderr 全体が欲しければオプションに stderr コールバックを渡します。

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({
    prompt: "...",
    options: { stderr: (data) => console.error("[claude stderr]", data) }
  })) {
    // ...
  }
} catch (err) {
  console.error(String(err)); // "Claude Code process exited with code 1. stderr: ..."
}

Claude Code returned an error result

CLI が終了前にエラー結果を報告した場合、両 SDK ともプロセス終了エラーの代わりに Claude Code returned an error result: <CLI 自身のエラー報告> を出します。コロンの後ろが CLI による原因の説明なので、まずそこを読みます。Python では ResultError（data 属性に結果全体）、TypeScript では同じ形のメッセージを持つプレーンな Error です。

structured_output が空のとき

結果メッセージの subtype が "success" なのに、structured_output が Python で None、TypeScript で undefined になることがあります。実行は完了していますが、検証済みの出力はありません。

アプリ側ではこれを失敗として扱い、subtype が success であることと structured_output があることの両方を確かめてから使います（書き方は Agent SDK の構造化出力を参照）。そのうえで次の原因を疑います。

• Claude が依頼を断った: 結果メッセージの stop_reason が "refusal" かどうかで判定できます。
• どんな出力も満たせないスキーマ: 例えば minLength が maxLength より大きい文字列。正しいはずのスキーマで繰り返し空になるなら、矛盾する制約を探します。見つからなければ出力が通るまでスキーマを単純にし、制約を1つずつ戻していきます。

解決しないときの報告先

ここに無いエラーは、SDK のリポジトリで既存の issue を探すか、新しく報告します。報告にはエラー全文と SDK のバージョンを含めます。

• TypeScript: claude-agent-sdk-typescript
• Python: claude-agent-sdk-python

旧 Claude Code SDK から移行したばかりでエラーが出る場合は、Claude Code SDK から Agent SDK への移行でパッケージ名やオプション名の変更も確認してください。

本ページは Troubleshoot the Agent SDK を中心に、Python SDK リファレンス（cli_path・stderr オプション、CLINotFoundError・ProcessError・ResultError の定義）と TypeScript SDK リファレンス（pathToClaudeCodeExecutable・stderr オプション、同梱バイナリ）を照合した非公式の日本語解説です（確認日 2026-11-04）。最新の仕様は公式ドキュメントを確認してください。