「Agent terminated early」の対処 — Claude Codeのサブエージェント中断エラー

Agent terminated early due to an API error: <error detail> — Claude Codeでサブエージェントを走らせているときにこう出たら、そのサブエージェントのAPIリクエストが回復不能な形で失敗し、タスクを終える前に止まったことを意味します。コロンの後ろに続く詳細が原因を特定する手がかりです。まず何が起きたかを切り分け、次に再開の手順に進みます。

「Agent terminated early」の意味

「Agent terminated early due to an API error」とは、サブエージェントのAPIリクエストが終端的に失敗し、そのサブエージェントがタスクを完了できないまま終わったことを示すエラーです。使用量上限への到達や、サーバーエラーでリトライを使い切ったことが典型的な原因になります。

このメッセージが出るのはClaude Code v2.1.199以降だけです。それより前のバージョンでは、専用のエラー表示はありませんでした。APIエラーのテキストがそのままサブエージェントの成果物としてClaudeに渡り、あたかも正常な出力の一部であるかのように扱われていました。エラーで止まったことに気づけないまま処理が進む、という失敗の仕方です。v2.1.199以降は、失敗が失敗として明示的に返るようになっています。

コロン以降の詳細で原因を切り分ける

エラーメッセージのコロンより後ろに、実際に失敗した理由が続きます。この詳細部分は、Claude Codeのエラーリファレンスにある他のセクションの見出しとほぼ対応しているため、そのまま検索の手がかりに使えます。

サブスクリプション利用でよく出るのは使用量上限系とサーバーエラー系です。API経由で自動化を組んでいる場合は、レート制限やクレジット残高の枯渇も珍しくありません。詳しい切り分けはClaude rate limitエラーの対処で扱っています。

フォアグラウンドとバックグラウンドで挙動が違う

同じAPIエラーでサブエージェントが止まっても、フォアグラウンドで動いていたかバックグラウンドで動いていたかによって、Claudeが受け取る情報は変わります。この違いを知らずに読むと、なぜ同じエラーが出たり出なかったりするのか分からなくなります。

フォアグラウンドで動くサブエージェントが、レート制限や過負荷、サーバーエラーで打ち切られたとき、それまでにテキストを出力し終えていれば、Agentツールはその部分出力を「不完全」の注記付きでそのまま返します。この場合はこのエラーになりません。出力が何もない、またはツール呼び出しだけだった場合に限って、このエラーで終わります。バックグラウンドで動くサブエージェントは常に失敗としてマークされ、終了時のメッセージにAPIエラーの内容と最後の出力が含まれるため、途中までの作業が失われることはありません。

v2.1.199の前後でどこまで挙動が変わったか

このエラー自体がv2.1.199での追加ですが、同じバージョン内でも細部の挙動はさらに調整が続いています。

v2.1.199はこのエラーメッセージが導入されたバージョンであると同時に、挙動が完全に固まる前の過渡的なリリースでもあります。ツール呼び出しだけで終わったサブエージェントの扱いは、その直後のリリースでさらに調整されました。厳密な版を確認したい場合は公式のエラーリファレンスで最新の記述を照合してください。

失敗したサブエージェントは/tasksに残らない

このエラーで終わったサブエージェントを、あとから/tasksで見つけようとしても見つからないことがあります。成功して完了したバックグラウンドのサブエージェントは、完了扱いで/tasksのリストに残り、詳細ビューも開いたままです。ところが失敗したサブエージェント、あるいは自分で止めたサブエージェントは、このリストから消えます。

画面下のサブエージェントパネルでの扱いも同じ非対称です。成功したサブエージェントの行はすぐに消え、フッターに「/tasks to see subagents」という案内が30秒だけ出ます。失敗したサブエージェントの行は、その場では30秒残り続け、選択してxを押せばすぐに消せます。エラーの詳細を確認したいなら、パネルから消える前にその30秒の間に読んでおく必要があります。

中断したサブエージェントを再開する

原因が解消したら、サブエージェントを最初からやり直す必要はありません。Claudeに「続きをやって」と伝えれば、同じエージェントIDで再開されます。完了・失敗を問わず、サブエージェントはSendMessageで名前かIDを指定すると自動的にバックグラウンドで再開する仕組みになっています。

再開が効かない場合に確認する点は2つです。ひとつは、エラー詳細に書かれた根本原因が本当に解消しているか。使用量上限が原因なら、リセット時刻を過ぎるまで再開しても同じエラーを繰り返します。もうひとつは、名前で指定したサブエージェントが別のセッションで再スポーンされて同じ名前を再利用していないか。Claude Codeはv2.1.199以降、名前が指すサブエージェントが会話の中で変わっていないかを確認し、ズレがあれば送信を拒否します。

サブエージェントの設計や並列実行の考え方はClaude Code Sub-agents完全ガイドにまとめています。エラーメッセージが導入された経緯やサイレント失敗対策の全体像はClaude Code v2.1.199のリリースノートで確認できます。

リトライの粘りを調整する

使用量上限やクレジット枯渇のような容量系のエラーは、リトライ回数を増やしても解消しません。原因そのものを解消する必要があります。一方、サーバーエラーや一時的な接続断のような容量系ではないエラーは、リトライの粘りを環境変数で伸ばせます。

export CLAUDE_CODE_RETRY_WATCHDOG=1

無人で長時間サブエージェントを回す構成では、この設定でリトライ回数の既定値が引き上がり、上限も外れます。ただし対象は容量系ではない一時エラーに限られ、使用量上限に達した状態を粘って通す仕組みではありません。環境変数の一覧と設定の書き方はClaude Code環境変数リファレンスにまとめています。

よくある質問

テキスト出力が一部あった場合も同じエラーになりますか

なりません。フォアグラウンドのサブエージェントがすでにテキストを出力していた場合、その部分出力は「不完全」の注記付きでそのまま返され、「Agent terminated early due to an API error」にはなりません。このエラーになるのは、出力が何もない、またはツール呼び出しだけだった場合です。

バックグラウンドのサブエージェントが失敗したら作業内容は消えますか

消えません。バックグラウンドで動くサブエージェントがAPIエラーで失敗すると、終了時にClaudeが受け取るメッセージにAPIエラーの内容と、そのサブエージェントの最後の出力が含まれます。途中までの作業は残った状態で失敗が報告されます。

エラー詳細に何も書かれていないときはどうしますか

コロンの後ろが空、または短い場合でも、エラーメッセージの直前後にClaude Codeが表示していた他のログを確認してください。多くの場合、サブエージェントを呼び出した直後の会話に、使用量上限やサーバーエラーを示す別の表示が残っています。

「Concurrent subagent limit reached」とは違いますか

違います。「Concurrent subagent limit reached」は、同時に動くサブエージェントが既定の20を超えたときに出るエラーで、APIエラーではなく同時実行数の上限そのものです。v2.1.217以降、この上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変更でき、ultracode使用中のセッションでは適用されません。「Agent terminated early due to an API error」はAPIリクエストの失敗が原因で、原因の層がまったく別です。

古いバージョンでは同じ状況をどう見分けますか

v2.1.199より前では専用のエラー表示がないため、サブエージェントの回答として不自然なJSON断片やHTTPエラーらしき文字列が返ってきていないかを見てください。それがAPIエラーのテキストがそのまま結果として扱われているサインです。バージョンを更新すれば、以降は明示的なエラーとして表示されます。

まとめ

「Agent terminated early due to an API error」は、サブエージェントのAPIリクエストが回復不能な形で失敗し、タスクを終えられなかったことを示すエラーです。コロン以降の詳細を、使用量上限・サーバーエラー・レート制限・クレジット残高のどれに当たるか切り分けるところから始めます。フォアグラウンドですでにテキストが出ていた場合はこのエラーにならず、バックグラウンドの失敗では最後の出力が保持される、という2つの挙動の違いを押さえておくと、同じエラーでも状況ごとの読み方を誤りません。原因が解消したら、サブエージェントは最初からやり直さず、続きをやるようClaudeに伝えるだけで同じエージェントIDのまま再開できます。