【Claude Code 連載第107回】エラーリファレンスの歩き方（errors）

よっしー

こんにちは。よっしーです(^^)

背景
1. 一言でいうと
2. どういう場面で役立つか
3. コードと仕組みの解説
4. まとめ
1. 次回予告

背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

公式ドキュメント：https://code.claude.com/docs/ja/errors

1. 一言でいうと

Claude Code が実行中に表示するエラーメッセージを、表示された文言から引いて「何が起きたか」「どう直すか」を調べるための辞書です。サーバーの障害、使用制限、認証、ネットワーク、リクエストの中身、コマンドライン、プラグイン、ツール、バックグラウンドセッションなど13の分類に、250を超えるエラーが載っています。加えて、エラーを表示する前に Claude Code が自動で何を再試行しているか、そしてエラーは出ていないのに「いつもより答えが悪い」と感じるときに何を確かめるか、という2つの重要な節を持っています。

ラッパーや IDE が出すエラーを除き、ここに載っているエラーと復旧のコマンドは、CLI・Desktop アプリ・クラウドセッションのすべてに当てはまります。3つとも同じ Claude Code の CLI を包んで動いているからです。インストール中のエラー（command not found や TLS のエラーなど）は、別の「インストールとログインのトラブルシューティング」のページが担当します。

原文は約6,200行、コードブロックは299本（ほとんどがエラーメッセージの実例）で、第104回の TypeScript リファレンスを超える連載最大のページです。この記事は、エラーを引く前に知っておくべき仕組み（自動再試行、途中で切れた応答、品質の確認）と、よく出会う代表的なエラーに絞ります。個々のエラーの対処は、表示された文言で原文を検索してください。

2. どういう場面で役立つか

シーン1：見たことのないエラーが出た

原文の冒頭には「エラーを見つける」という表があり、表示されたメッセージから該当する節に飛べます。エラーの文言をそのまま原文で検索するのが最も早い使い方です。

シーン2：同じエラーが繰り返し出て、待つべきか直すべきか分からない

エラーには、待てば直るもの（サーバーの一時的な障害、使用制限のリセット待ち）と、設定を直さない限り何度でも出るもの（無効な API キー、証明書のエラー、ポリシーによる拒否）があります。原文は、Claude Code がエラーを見せる前に何をすでに再試行しているかを詳しく書いているので、「表示された時点で、もう一度試しても無駄か」を判断できます。

シーン3：エラーは出ていないのに、答えの質が落ちた気がする

原文の最後の節は、まさにこの場面のためのものです。モデルが勝手に変わったのか、会話の状態のせいなのかを切り分ける手順が書かれています。

不要・向かないケース

インストールの失敗：別のトラブルシューティングのページが担当です。
MCP サーバーの接続・認証の失敗、フックの失敗：それぞれ MCP のページ（第8回）、フックのページ（第11回）に回されています。
Agent SDK のアプリが受け取る例外：第97回の SDK のトラブルシューティングが担当です。ただし SDK も同じ CLI を動かしているので、API Error などの中身はこのページで引けます。

3. コードと仕組みの解説

原文の fenced コードブロックは299本で、ほぼすべてがエラーメッセージの実例です。この記事では、代表的な9本だけを引用し、残りは分類の地図と表に圧縮します。コードは原文から機械的に抜き出したもので、変えていません。メッセージ中の <model>・<tool> や時刻などは、実際には具体的な値が入る箇所です。

3-0. 13の分類

原文の分類と、そこに載っているエラーの数（見出しの数）です。

分類	数	代表的な内容
サーバーエラー	8	500、529（過負荷）、タイムアウト、応答なし、途中で切れた応答、auto モードの判定不能
使用制限	9	セッション・週間・モデル別の上限、1M コンテキストの使用クレジット、429、支出上限、残高不足
認証エラー	42	未ログイン、無効な API キー、`apiKeyHelper` の失敗、組織のポリシー、Remote Control、OAuth、AWS・Google Cloud・Foundry の認証、Cloud ゲートウェイ
ネットワークと接続エラー	15	API に接続できない、SSL 証明書、プロキシの拒否、クラウドセッションの許可外ホスト
リクエストエラー	36	長すぎるプロンプト、画像・PDF、ツールのスキーマ、モデルの指定、思考の設定、使用ポリシー・サイバーセキュリティの警告
コマンドラインエラー	58	フラグの競合、`--agents`、クラウドセッション、MCP サーバーの追加、ultrareview、GitHub 連携、セッションの再開
プラグインエラー	13	マーケットプレイスの信頼・名前、`user_config`、アーカイブの整合性、パスの逸脱
ツールエラー	22	存在しないツール、Read の拒否ルール、`subagent_type`、セッション間メッセージ、WebFetch の localhost
バックグラウンドセッションエラー	19	拒否されたコマンド、worktree の分離チェック、セッションの応答なし、起動時の EACCES など
ラッパーと IDE エラー	3	`Claude Code process exited with code N`、PATH に CLI が無い
Rewind の警告とエラー	2	一部のファイルを飛ばした、何も復元されなかった
セッション保存の警告	3	トランスクリプトの書き込み失敗、保存がオフになっている
設定の警告	29	読み込まれなかった指示ファイル、管理設定、権限ルールの書き方、モデル ID

数は筆者が原文の見出しを数えたものです。認証とコマンドラインの2つで全体の4割近くを占めます。これまでの連載で扱った機能（Remote Control、ultrareview、バックグラウンドセッション、セッション間メッセージ、プラグイン、管理設定など）のエラーが、ここに集まっていることが分かります。

3-1. 自動再試行：エラーが見えた時点で、何はもう試されたか

このページで最も重要な前提は、Claude Code は一時的な障害を、指数バックオフで最大10回まで再試行してからエラーを見せることです。表示されたエラーについては、その障害に当てはまる再試行はもう済んでいます。

再試行の対象と対象外を、原文の箇条書きから整理します。

再試行する	再試行しない
応答がまだ1文字も流れていない段階のサーバーエラー・過負荷・タイムアウト	TLS 証明書の検証失敗（検査プロキシ、`NODE_EXTRA_CA_CERTS` の欠落、期限切れの証明書）。最初の試行で報告する
思考を終えた後、テキストやツール呼び出しを始める前のサーバーエラー（最大2回）	テキストのブロックやツール呼び出しを1つ完了した後の障害。同じツール呼び出しが2回実行されうるので再実行しない
切れた接続、スリープによる切断、止まったストリーム（条件により1〜2回）	応答を終えた後の障害（再試行するものが無い）
一時的な 429 のスロットリング（ゲートウェイの支出上限による 429 は除く）	書き換えるゲートウェイを通った Bedrock の想定外の content-type
入力と `max_tokens` の合計がコンテキストを超えたリクエスト（`max_tokens` を減らして。だめなら圧縮へ）	組織のポリシーチェック（Inference hooks）による拒否。同じモデルにもフォールバックモデルにも再送しない
Google Cloud・AWS の認証情報の読み込み失敗（最大2回）、`apiKeyHelper` 使用時の 401・403（スクリプトを再実行）	非ストリーミングの再試行で、成功ステータスなのに本文が空・壊れているもの

表は筆者の整理です。左の列の最後の行は、第94回の「ANTHROPIC_BASE_URL のプロキシでキーを差し込む」や第95回のプロキシの構成で、キーの入れ替えを apiKeyHelper の再実行で拾ってくれる、ということでもあります。

右の列の2行目が、このページの考え方の中心です。Claude がすでに完了したテキストやツール呼び出しがある状態で障害が起きたら、Claude Code はリクエストをやり直さず、完了した分を残して先へ進む。ツール呼び出しを二重に実行しない、という安全側の設計です（3-2）。

再試行中に見えるもの

再試行中、スピナーにはエラーのラベルの後に Retrying in Ns · attempt x/y のカウントダウンが出ます。ネットワークが落ちている、TLS のハンドシェイクに失敗した、レート制限に達した、のようにすぐ対処できる障害では最初から具体的な理由が出て、それ以外は最初は API error と出て3回目から具体的な理由に変わります（v2.1.198 以降）。リクエストが保留中で20秒間データが届かないと、Waiting for API response · will retry in … · check your network のバナーが出ますが、この時点ではまだ失敗していません。advisor に相談している間は、このしきい値が90秒になります。

再試行を調整する環境変数

変数	既定	効果
`CLAUDE_CODE_MAX_RETRIES`	10	再試行の回数（上限15）。スクリプトで早く失敗させたいなら下げる
`CLAUDE_CODE_RETRY_WATCHDOG`	未設定	無人のセッション（CI など）で `1` にすると、429・529 の容量エラーを無期限に再試行する。他の一時的なエラーの既定回数も300（約3時間分）に上がる。支出上限や使用クレジットの枯渇による 429 は即座に失敗（v2.1.239 以降）
`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`	未設定	上の設定のとき、429・529 の解消を待つ最大時間（v2.1.295 以降）
`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`・`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`	500・32000	529 のバックオフの開始・上限の遅延
`API_TIMEOUT_MS`	600000	リクエストごとのタイムアウト。応答ヘッダーを待つ上限にもなる
`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`	未設定	タイムアウトした非ストリーミングのリクエストの再送回数の上限（v2.1.285 以降）
`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`	未設定	ストリーミングの最初の1バイトの期限（v2.1.242 以降）

表は原文の表を要約したものです。第104回で SDK の側から見た API_TIMEOUT_MS・CLAUDE_CODE_MAX_RETRIES・CLAUDE_CODE_RETRY_WATCHDOG の、本体側の詳細がここです。

3-2. 途中で切れた応答：「The response above may be incomplete」

3-1 の「完了した分を残して先へ進む」の結果として表示されるのが、この通知です。

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection lost mid-response. The response above may be incomplete.
API Error: Your computer went to sleep mid-response. The response above may be incomplete.
API Error: The response stopped arriving. The response above may be incomplete.
API Error: Part of the response never arrived. The response above may be incomplete.
API Error: The response stream was malformed. The response above may be incomplete.

末尾が共通で、前半が原因を表します。Server error mid-response はストリームの途中の過負荷・5xx、Connection lost mid-response は切断（プロキシやゲートウェイが応答の途中で本文を閉じた場合も）、Your computer went to sleep mid-response はスリープの検出、The response stopped arriving はストリームの監視による中止、Part of the response never arrived は途中のイベントの欠落、The response stream was malformed は壊れたイベントです。

扱いの要点は次のとおりです。

対話セッションでは、画面に残っている応答を読み、continue と返信すれば、Claude は最後に完了したブロックから再開します。中断された最後のブロックは捨てられるので、最後の文やツール呼び出しが欠けていることがあります。
非対話セッション（-p、Agent SDK、クラウドセッション）では、途中で切れた応答がメインの会話にあり、テキストだけでツール呼び出しを含まない場合、Claude Code は自分で Claude に続きを促します（最大3回連続、v2.1.246 以降）。通知が出るのは、それを使い切った後だけです。
サブエージェントでも同じく続きを促します（v2.1.257 以降）。
応答を終えた後に切れた場合は、通知なしで普通に終わります（v2.1.222 以降。それ以前は完全な応答でもエラー扱いになることがあった）。

-p の既定のテキスト出力では、最後に完了したテキストのブロックの後にこのメッセージが出ます。--output-format json・stream-json では result フィールドに入ります。第97回で見た Agent SDK の「Claude Code returned an error result:」の後ろに来るのも、この種の報告と考えられます（筆者の対応づけ）。

3-3. auto モードが判断できないとき

第80回・第104回で見た auto モード（分類器のモデルがシェルコマンドやネットワーク要求を審査する）には、分類器そのものが失敗したときのエラーがあります。

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

作業ディレクトリの中の読み取り・検索・編集は分類器を通らないので、このエラーが出ている間も動き続けます。止まるのは分類器の判断が要る操作だけです。括弧の中にカテゴリ（(rate-limited)・(overloaded)・(server error)・(timed out)・(connection failed)）が付くこともあります。

原文はこの節で、分類器の失敗の型をいくつか挙げています。

状況	動き	対応
分類器のモデルが一時的に使えない	承認しない（安全側）	数秒後に再試行。Claude も通常は自動で再試行する。Bedrock で毎回出るならアカウントがそのモデルを呼べるか確かめる
分類器の応答が解析できない	安全のためブロック	再試行（通常は次で成功）、`claude --debug` で詳細
会話の以前の内容が、auto モードとは別の API の安全チェックを起動した	アクションを拒否するが、Claude には「アクションが危険という判断ではない」と伝える。一時停止のしきい値に数えない	再試行は無駄。別の権限モードに切り替えて手で承認するか、新しい会話で
会話が分類器のコンテキストより大きい	対話では通常の確認画面に戻る。`-p` で確認の手段が無ければ、そのアクションは実行されない	`/compact`

表は筆者の整理です。どの場合も、判断できないときは承認しない方向に倒れていることが分かります（筆者の指摘）。4行目の -p の扱いは、第75回の「-p は確認画面を出せない」の帰結です。

3-4. 使用制限

サブスクリプションのプランで許容量を使い切ると、次のいずれかが出ます。

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

ここには見落としやすい区別があります。セッションの上限と週間の上限はすべてのモデルで共有されているので、モデルを替えても戻りません。一方、Opus・Sonnet の上限はそのモデルの系統だけに掛かるので、/model で別の系統に替えれば続けられます。ただしモデルごとにプロンプトキャッシュが別なので、替えた直後のリクエストは会話全体を読み直します（第92回のキャッシュの話）。

claude.ai のサブスクリプションでログインした対話セッションでは、Claude Code は開いたセッションのまま待ち、リセット直後に中断したタスクを続けることもできます（v2.1.234 以降）。Desktop アプリの「Auto-continue when limits reset」と CLI の /config の「Continue automatically at usage limit」は別の設定なので、止めたいならそれぞれで止めます。

関連して、1M のコンテキストを使うモデルで Usage credits required for 1M context が出るのは、許容量の枯渇ではなく権利の確認です。許容量が残っていても出ます。/model で [1m] の付かない版を選ぶか、使用クレジットを有効にします。

API キーや Bedrock・Google Cloud のプロジェクトのレート制限に達すると、次が出ます。

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

原文の対応の1つ目が実務的です。/status で、使われている認証情報が想定どおりか確かめる。環境に紛れ込んだ ANTHROPIC_API_KEY のせいで、サブスクリプションではなく低いティアのキーでリクエストが送られていることがあるからです。

3-5. 認証：多くは「どの認証情報が使われているか」の問題

認証エラーは42項目と最大の分類ですが、代表的なものは2つです。

Not logged in · Please run /login

Invalid API key · Fix external API key

どちらにも共通する原文の対応が、/status で、Claude Code が実際に使っている認証情報の出どころを確かめることです。無効な API キーでは、さらに次の注意があります。

同じシェルで env | grep ANTHROPIC（PowerShell では Get-ChildItem Env:ANTHROPIC*）を実行する。direnv、dotenv のシェルプラグイン、IDE のターミナルは、明示的に設定しなくても、プロジェクトの .env から古いキーを読み込むことがある。
Fix external API key の後に「it contains a line break at character 41」のような説明が続く場合、キーは API に届いていない。Claude Code が HTTP ヘッダーに入れられない文字（改行など）を見つけて、送る前に止めている。

Not logged in については、同じ設定ディレクトリを使う別の Claude Code のウィンドウで claude.ai にログインすると、表示中の対話セッションも自動でそのログインを使い始めます（再起動不要）。CI のように対話でログインできない環境では、起動時にキーを取ってくる apiKeyHelper を設定します。

第78回で見た「.env は SDK が自動で読まない」と、ここでの「シェルの道具が .env を勝手に読む」は、表裏の関係です。どの経路でキーが入ってくるかを把握していないと、意図しないキーで動く、ということです（筆者の指摘）。

3-6. リクエストエラーの代表：長すぎるプロンプトとポリシーの拒否

Prompt is too long

会話と添付がモデルのコンテキストを超えたときのエラーで、対話セッションでは次のように表示されます。

Context limit reached · /compact or /clear to continue

自動の圧縮（auto-compact）は既定でオンで、通常はこのエラーを防ぎます。原文の対応で、第70回のコンテキストの回とつながるものを挙げます。

/context で、何がウィンドウを占めているか（システムプロンプト、ツール、メモリファイル、メッセージ）を見る。
使っていない MCP サーバーを /mcp disable <name> で外し、ツール定義を減らす。
大きな CLAUDE.md を削るか、パスに限ったルールに移す。
/compact が Not enough messages to compact. と答えるなら、会話は1回のやりとりだけで、要約するものが無い。/clear して、貼り付けを減らすか小さい添付で送り直す。
大きなウィンドウを持つモデルで 200K トークン付近でこのエラーが出るなら、Claude Code が知らないモデル ID を使っている可能性がある。知らない ID には 200K のウィンドウを想定するので、実際のウィンドウを指定する（ゲートウェイ経由のモデル ID で起こりやすい）。

使用ポリシーによる拒否

API Error: Opus 4.6 can't help with this. Start a new session to continue.

Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

このエラーで最も大事な説明は、チェックは最新のプロンプトだけでなく会話全体を評価することです。だから同じセッションで新しいメッセージを送っても、--continue・--resume で開き直しても、ディスクのトランスクリプトに原因の内容が残っている限り、同じ拒否が繰り返されます。対応は、Esc を2回押すか /rewind で原因のターンより前に戻って言い換える（第69回のチェックポイント）、原因が分からなければ /clear で新しい会話を始める、です。-p では新しいセッションで言い換え、--model で別のモデルにすると解消することもあります（ポリシーのチェックはモデルによって違うため）。

サイバーセキュリティの話題として警告された場合は別のメッセージになり、正当な作業なら Cyber Verification Program への申請、誤検知なら /feedback が案内されます（Bedrock・Agent Platform・Foundry では使用ポリシーの拒否のメッセージになる）。

推論の書き出しを求めたと判断された場合

拒否のメッセージに次の行が含まれていたら、別の原因です。

Details: `[reasoning_extraction]`

Claude の内部の推論を、そのまま、または決まった形式で応答に書き出させる指示（<thinking> セクション、スクラッチパッドの節、JSON 出力の reasoning フィールドなど）が原因です。その指示はプロンプトだけでなく、CLAUDE.md、スキル、サブエージェントのプロンプト、出力スタイル、MCP ツールの説明に入っていることもある、と原文は書いています。カスタマイズが原因かどうかは、claude --safe-mode でカスタマイズを無効にしたセッションで同じプロンプトを送って確かめます。説明や根拠を短く求めることは引き続きできます。

第98回の構造化出力で、スキーマに「推論」のようなフィールドを入れたくなる場面がありますが、それがこの拒否の引き金になりうる、ということです（筆者の指摘）。

3-7. 答えの質が落ちたと感じたとき

エラーは出ていないのに答えの質が落ちたと感じる場合、原文は「原因は通常、モデルそのものではなく会話の状態」だと書いています。そして、Claude Code がモデルの版を黙って変えることはないと明言し、フォールバックのモデルに切り替わるのは次の3つの場合だけだとしています。

切り替わる場合	見え方
設定した `--fallback-model` が、可用性のエラーの後にそのターンだけ引き継ぐ	トランスクリプトに通知
Bedrock・Agent Platform の起動時チェックが既定のモデルを使えないと判断した、またはセッション中にアクセスを失った	`/model` で確認できる
自動のモデルフォールバック（Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5、Opus 5）が、警告されたカテゴリのセッションを別のモデルへ移す	トランスクリプトに通知、`/model` で確認できる

表は原文の記述を筆者がまとめたものです。そのうえで、確かめる順番は次のとおりです。

モデル：/model で想定のモデルか確かめる。以前の /model の選択や ANTHROPIC_MODEL で小さいモデルになっていることがある。
effort：/effort で推論のレベルを確かめ、難しいデバッグや設計では上げる。既定はモデルで違う。
コンテキストの圧迫：/context で埋まり具合を見て、区切りで /compact、または /clear。
古い指示：大きい・古い CLAUDE.md や MCP のツール定義がコンテキストを使い、応答を引っ張る。/doctor が大きすぎるメモリファイルや使っていない拡張を指摘する。

原文はさらに、うまくいかなかった応答には、訂正を返信するより巻き戻すほうが効くと書いています。スレッドの中で訂正すると、間違った試みがコンテキストに残り、後の答えをそちらに引き寄せるからです。Esc を2回か /rewind で悪いターンの前に戻り、より具体的なプロンプトで言い直します。それでもおかしいなら /feedback で報告します（トランスクリプトが付くので、Anthropic が実際の劣化を診断する最も速い方法、と原文は書いています）。

この「巻き戻すほうが効く」は、第69回のチェックポイントの使いどころそのものです（筆者の対応づけ）。

3-8. ここに無いエラーを報告する

手段	内容
`/feedback`	トランスクリプトと説明を Anthropic に送る。事前入力された GitHub issue を開く選択肢もある。Bedrock・Agent Platform・Foundry などでは、担当者に渡せるローカルのアーカイブを保存する
`claude doctor`／`/doctor`	シェルからは読み取り専用の診断、Claude Code の中では設定の問題を見つけて直すチェックアップ
status.claude.com	進行中の障害を確かめる
GitHub の既存の issue	同じ問題が報告されていないか探す

4. まとめ

このページは、表示されたエラーの文言から引く辞書。13分類・250超のエラー。CLI・Desktop・クラウドセッションに共通（ラッパーと IDE のエラーを除く）。
表示された時点で、該当する再試行はもう済んでいる。一時的な障害は指数バックオフで最大10回。TLS 証明書の失敗、組織のポリシーによる拒否は再試行しない。
テキストやツール呼び出しを完了した後の障害は再実行しない（ツールの二重実行を避ける）。完了分を残し「The response above may be incomplete」。対話では continue、非対話とサブエージェントでは自動で最大3回続きを促す。
無人実行は CLAUDE_CODE_RETRY_WATCHDOG を 1 にして 429・529 を待ち続けられる（支出上限の 429 は即失敗）。
auto モードの分類器が判断できないときは承認しない。作業ディレクトリ内の読み書き・検索は止まらない。
使用制限：セッション・週間は全モデル共有、Opus・Sonnet は系統別。1M コンテキストのエラーは枯渇ではなく権利の確認。
認証・429 は、まず /status で実際の認証情報を確かめる。.env を読むシェルの道具に注意。
使用ポリシーの拒否は会話全体が評価されるので、/rewind か /clear。[reasoning_extraction] は推論の書き出しの指示が原因で、カスタマイズに潜むこともある（claude --safe-mode で確認）。
質が落ちたと感じたら、モデルは黙って変わらないので、モデル・effort・コンテキスト・古い指示の順に確かめ、悪いターンは訂正より巻き戻す。

次回予告

次回は 「設定リファレンス」（settings-reference） を取り上げる予定です。

今回のエラーの多くは、apiKeyHelper、autoCompactEnabled、管理設定のロック、サンドボックスの許可エントリといった、設定ファイルの項目と結びついていました。これまでの回でも、policyHelper・modelSettings・extraKnownMarketplaces など、詳細を「設定リファレンス」に回してきた項目がたくさんあります。次回は、Claude Code の設定ファイルにどんな項目があり、それぞれ何を決めるのかを、地図として見ていきます。

よっしー

何か質問や相談があれば、コメントをお願いします。また、エンジニア案件の相談にも随時対応していますので、お気軽にお問い合わせください。

それでは、また明日お会いしましょう(^^)