目次
Claude Code で作業中、突然エラーで止まる——「ログインし直せ」「レート制限」「プロンプトが長すぎる」「MCPが繋がらない」。種類が多くて、その都度ググるのも面倒だ。本記事は Claude Code でよく出るエラーを、原因と「叩くべきコマンド」付きで一覧化した実務リファレンスである。
先に結論。多くのエラーは、まず claude doctor（総合診断）・/status（今の認証状態）・/context（コンテキスト内訳）の3つを叩けば原因の当たりが付く。そして頻出するのは ① 使用量・レート制限、② コンテキスト超過、③ 認証切れ、④ MCP接続失敗の4系統。以下、カテゴリ別に「症状 → 原因 → 対処コマンド」で整理する。ブックマークして、詰まったときに該当箇所を引いてほしい。
迷ったら、この3コマンド
— 大半のエラーは原因の切り分けから
頻出4系統：① 使用量・レート制限 ② コンテキスト超過 ③ 認証切れ ④ MCP接続失敗。
そして 「最新版に更新」claude update が地味に多くのバグを解決する。
※本記事のコマンド・対処は Claude Code 公式ドキュメント（2026年時点）に基づく。Claude Code は更新が速く、コマンド名やメッセージ文言は変わり得る。最新は claude doctor と公式ドキュメントで確認を。
1. 詰まったら最初に叩く「診断コマンド」
個別のエラーに入る前に、原因の切り分けに効く診断コマンドを覚えておくと、ほとんどの問題は素早く特定できる。
| コマンド | 何が分かる／できる |
|---|---|
claude doctor | インストール・設定・MCPサーバー・コンテキスト使用量の総合チェック |
/status | いま有効な認証方式（Pro / Max / Team / APIキー） |
/context | コンテキストの内訳（システムプロンプト・履歴・ファイル・MCPツール） |
/usage | 現在のプラン上限とリセット時刻 |
/permissions | 権限ルール（allow/deny）の一覧と出所 |
/mcp | MCPサーバーの接続状態・公開ツール数 |
/feedback | 不具合を会話ログ付きでAnthropicに報告 |
2. 認証・ログイン系
「使えていたのに急にログインを求められる」系。環境変数のAPIキーがサブスクリプションを上書きしているのが定番の罠だ。
| 症状 | 原因 | 対処 |
|---|---|---|
| Not logged in · Please run /login | このセッションで使える資格情報が無い（保存したログインの更新が拒否されて消えた場合は Login expired · Please run /login と表示される） | /login。繰り返すなら端末の時計ずれ・キーチェーンロックを確認 |
| Invalid API key · Fix external API key | ANTHROPIC_API_KEY や apiKeyHelper のキーがAPIに拒否された（古いキーの残存など） | env | grep ANTHROPIC で確認 → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | 全端末でサインアウトした／管理者がアクセスを外した（revoked）、自動更新の失敗（expired） | /login。同じセッションで再発したら /logout → /login。起動のたびに出るなら時計ずれも疑う |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | 無効化された組織の古い ANTHROPIC_API_KEY が使われている。環境変数が無いのに出るなら /login 側の組織が無効 | シェル設定（.zshrc等）からキーを削除 → /login → /status で確認。環境変数が無いなら、サポートに連絡するか別のアカウントで入る |
| 403 Forbidden（ログイン後） | サブスク失効・ロール不足・プロキシ干渉 | サブスク状態とConsoleロールを確認。プロキシ環境は HTTPS_PROXY を設定 |
鉄則：「環境変数のAPIキー」はサブスクリプションログインより優先される。会社のCI用などに ANTHROPIC_API_KEY を設定したまま忘れていると、個人のPro/Max契約が無視される。まず /status で「今どの資格情報で動いているか」を見るのが正解だ。環境変数 ANTHROPIC_API_KEY による上書き・トークン失効・キーチェーン等を深掘りした対処は 認証・ログインエラーの原因と対処 で。
3. 使用量・レート制限系（最頻出）
Claude Code で最も多い相談がこれ。公式のコスト管理ドキュメント（Manage costs effectively）によると、Claude Code の1ターンにはファイルの中身・ツール呼び出し・複数段階の推論が載るため、1回のデバッグで1日分のチャットを超える量を使うことがある。だから体感より早く上限に当たる。
「制限に当たった」ときの3手
/usage で上限とリセット時刻、/status で資格情報を確認/model で軽いモデルに、/compact で履歴圧縮、不要MCPを無効化
注意：「Server is temporarily limiting requests」はプラン上限ではなく一時的なサーバー側スロットル。少し待って再試行でOK。
プラン上限（session/weekly）とは別物なので混同しない。
補足：「API Error: Request rejected (429)」は、APIキー（または Amazon Bedrock／Google Cloud のプロジェクト）に設定されたレート制限の超過で、サブスクのつもりなら紛れ込んだ ANTHROPIC_API_KEY が無いか /status で確かめる。「Credit balance is too low」は Console のプリペイド残高切れか、サブスクのつもりが Console のAPIキーで送っている状態（チャージするか、/status でキーを確かめて外す）。なお2026年3月には、Claude Code の利用枠が想定よりずっと速く尽きるという苦情が Pro・Max の利用者から相次ぎ、Anthropic も最優先で調査していると認めた（The Register、2026年3月31日）。頻発するなら最新版更新と /usage での実測、必要なら /feedback 報告を。トークン節約の体系的な方法は AIトークン節約術・Claude Codeのトークン節約 も参照。「usage limit reached」の仕組み（5時間枠・週次枠）と上限到達時の対処は 使用量制限 reached の原因と対処 で詳説。
4. コンテキスト・トークン系
長い会議や巨大ファイルを扱うと出るのがこれ。
| 症状 | 原因 | 対処 |
|---|---|---|
| Prompt is too long | 会話＋ファイルがコンテキスト窓を超過 | /compact（要約）・/clear（リセット）・/context で内訳確認・不要MCPを /mcp で無効化 |
| Error during compaction: Conversation too long | 圧縮の出力分の空きが足りない | Esc 2回で数ターン巻き戻してから /compact。ダメなら /clear |
| Autocompact is thrashing | 圧縮直後に巨大出力で即再充填 | 大きいファイルは行範囲で分割して読む／/compact keep only ○○ で焦点指定／サブエージェントに分離 |
コツは 「巨大ファイルを丸ごと読ませない」こと。ログやデータは行範囲を指定して小分けに渡す。コンテキストウィンドウの考え方を押さえると、この種のエラーは激減する。「Prompt is too long」の詳しい原因と対処（200K/1M窓・サブエージェント活用）は コンテキスト上限エラーの解説 で。
5. サーバー・モデル系
| 症状 | 原因 | 対処 |
|---|---|---|
| 500 Internal server error | Anthropic側の一時障害 | status.claude.com を確認 → 1分後に再試行 |
| 529 Overloaded（連発） | API全体が一時的に高負荷 | 数分待つ。/model でモデルを変えて負荷分散 |
| Request timed out | 既定10分以内に応答が返らない | タスクを小さく分割。低速回線なら API_TIMEOUT_MS を引き上げ |
| There's an issue with the selected model / Model '…' not found | モデル名が不正 or 契約に含まれない | /model で選び直し。古い ANTHROPIC_MODEL 環境変数を確認 |
| Claude Opus is not available with the Claude Pro plan | 選択モデルがプラン対象外 | /model で利用可能モデルへ。プラン変更直後は /logout→/login で更新 |
「529 Overloaded」「500」がサーバ側の事象でなぜ自分の枠を消費しないのか、自動リトライ（最大10回）の仕組みや 429 との違いの詳細は 529 Overloaded・500 の原因と対処 で。
6. インストール・PATH・更新系
| 症状 | 原因 | 対処 |
|---|---|---|
| command not found: claude | インストール先がPATHに無い | ~/.local/bin（Win は %USERPROFILE%\.local\bin）をPATHに追加 |
| インストールが失敗（HTMLエラー等） | プロキシ・地域ブロック等 | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | 社内プロキシのTLS検査・CA証明書不足 | CA証明書を NODE_EXTRA_CA_CERTS=/path/ca.pem で指定。NODE_TLS_REJECT_UNAUTHORIZED=0 はNG |
| インストールが複数混在（バージョンの食い違い・予期しない動作） | native・npm・Homebrew・WinGet などの重複 | which -a claude（Windows は where.exe claude）で確認し、1つに統一。推奨は native の ~/.local/bin/claude。例：npm uninstall -g @anthropic-ai/claude-code |
| 古いバージョン由来の不具合 | 未更新 | claude update（多くのバグが解消する最優先策） |
| デスクトップ版が「このアプリを開くことができません」 | 更新時にMSIXパッケージが半端に登録された（Windows） | 常駐プロセスを終了してから設定の[修復]。詳説 |
command not found: claude の原因（PATH・複数インストールの衝突・npm権限・Windowsのシェル取り違え）と直し方は インストール・PATHエラーの原因と対処 で詳説。
7. ネットワーク・プロキシ系
社内ネットワークやVPN環境で多い。まず curl -I https://api.anthropic.com で疎通を確認する。
| 症状 | 原因 | 対処 |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | 未接続・VPN遮断・プロキシ未設定 | HTTPS_PROXY=http://proxy:8080 を設定。api.anthropic.com の許可をIT確認 |
| SSL certificate verification failed（社内） | 自己署名証明書の傍受 | ITからCAバンドルを入手し NODE_EXTRA_CA_CERTS に設定 |
| 403 host_not_allowed（クラウド実行） | クラウド環境の許可リスト外 | ネットワーク設定を Custom にして対象ドメインを許可 |
| Connection lost mid-response（v2.1.227 より前の表記は Connection closed mid-response） | 接続してストリームが流れ始めた後に切断された | 途中出力は残るので continue で再開。頻発するなら claude --version を確認して更新 |
プロキシ・TLS証明書（NODE_EXTRA_CA_CERTS）・許可ドメイン・NODE_TLS_REJECT_UNAUTHORIZED=0が危険な理由まで深掘りした対処は 接続・プロキシエラーの原因と対処 で。応答の途中で切れる Connection lost mid-response（旧表記 Connection closed mid-response） は届いた後の別問題で、応答が途中で切れるエラーの原因と対処 に切り分けとバージョン別の修正状況をまとめている。
8. MCP（連携サーバー）系
MCP サーバーを使い始めると遭遇する。まず /mcp で状態確認。
| 症状 | 原因 | 対処 |
|---|---|---|
| Server failed to connect / Pending approval | サーバー起動失敗・到達不可・認証待ち | /mcp で状態確認。stdioはコマンド存在＆実行権限、HTTPはURL/認証ヘッダを確認 |
| Tool not found | 接続済みだがツール未公開／名前違い | /mcp でツール数を確認、claude mcp get <name> で健全性確認 |
| 再接続試行が尽きた | HTTP/SSEサーバーが5回リトライ後も不通 | サーバー稼働を確認し /mcp で手動再接続。stdioは claude 再起動 |
| MCPサーバーのタイムアウト | 起動が MCP_TIMEOUT（既定30秒）以内に終わらない | MCP_TIMEOUT=60000 claude のようにミリ秒で延ばす。.mcp.json の "timeout" はツール実行ごとの上限で、起動の待ち時間とは別 |
MCP接続を failed・needs authentication・pending のステータス別に深掘りした対処（Windowsの npx は cmd /c ラップ等）は MCPが繋がらない時の原因と対処 で。
9. 権限・ツール系
「bypassモードなのに許可を求められる」系。要点は2つ。bypass でも確認が出る操作は公式に決まっていることと、deny ルールは bypass を含むどのモードでも実行をブロックすること（allow ルールは bypass では効果が無い。公式「Choose a permission mode」）。
| 症状 | 原因 | 対処 |
|---|---|---|
| bypassモードでも許可を求められる | 明示的な ask ルール、AskUserQuestion などユーザーの操作が要るツール、ルート・ホーム・作業ディレクトリなど重要パスを消す rm／rmdir（公式が circuit breaker と呼ぶ安全装置）は bypass でも確認が出る。.git・.claude など保護されたパスへの書き込みは bypass なら確認なし | /permissions で ask ルールを確認・調整。deny ルールは確認を出さずにブロックする |
| Tool execution denied by PreToolUse hook | フックが exit code 2 でブロック | .claude/settings.json のフックを確認。claude --debug で出力を見る |
なぜ bypass でも止まるのかの詳細は bypassモードでも許可を求める理由、権限設計の安全な考え方は 権限モードとセキュリティ を参照。
10. その他（thinking/画像PDF/IDE）
- thinking blocks cannot be modified（400）：拡張思考のブロックが履歴で壊れる既知バグ。Esc 2回 → /rewind、ダメなら新セッション、そして
claude update。詳細は thinking blocks 400エラー解説。 - court / 生の <invoke> タグが表示されツールが実行されない：ツール呼び出しの制御タグが壊れて生成される既知バグ。2回外したら新セッション(/clear)へ。詳細は court / invoke タグ漏れエラー解説。
- プルリクエストのステータスを確認できませんでした：GitHub接続（多くは
gh認証）の問題。gh auth statusから。詳細は PRステータスエラー解説。 - Image was too large / PDF too large：画像は長辺8000px超（多数の画像を扱うときは2000px超）、PDFは100ページ/20MB超で弾かれる。Esc 2回で添付を外し、リサイズ／行範囲読みに。大きいファイルは貼らずパス参照。
- VS Code拡張が繋がらない：VS Codeのターミナルで
claude --versionが通るか確認。PATHとVS Code再起動、拡張の再インストール。
11. エラー→対処 早見表
| こうなったら | まずこれ |
|---|---|
| 原因が分からない／全般 | claude doctor → /status → /context |
| 急にログインを求められる | /status →（古いキーがあれば）unset ANTHROPIC_API_KEY → /login |
| レート制限に当たった | /usage → /modelで軽量化 → /compact → 待つ |
| Prompt is too long | /compact → /clear → 巨大ファイルは行範囲で |
| 500/529/timeout | status.claude.com 確認 → 少し待つ → /model |
| command not found: claude | PATHに ~/.local/bin を追加 |
| 繋がらない（社内NW） | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCPが繋がらない | /mcp → URL/権限/コマンド確認 → MCP_TIMEOUT |
| bypassでも確認を求められる | /permissions で ask ルールを確認（重要パスの削除は bypass でも確認が出る） |
| とにかく直したい | claude update（最新版で多くが解消） |
まとめ
Claude Code のエラーは数あれど、初手は claude doctor / /status / /context の3コマンドで原因の切り分け——これでほとんどの問題は前に進む。頻出は 使用量・レート制限／コンテキスト超過／認証切れ／MCP接続失敗の4系統で、それぞれ /usage・/compact・/login・/mcp が一次対処になる。
そして見落としがちな最強の一手が claude update で最新版に保つこと。Claude Code は更新が速く、過去のバグ（thinking blocks 400 など）も版を上げるだけで直ることが多い。「詰まったら、まず診断3コマンド。直らなければ最新版へ」——この型を持っておけば、エラーで時間を溶かすことはなくなる。
なお、エラーではなく挙動の「重さ・速さ」が気になるなら、Claude Codeの工数（effort）設定を見直すと、思考量とトークン消費のバランスを調整できる。関連記事：thinking blocks 400エラー、PRステータス確認エラー、Claude Codeトークン節約、bypassでも許可を求める理由、MCPとは、The model returned no contentの原因と対処 も併読を。
FAQ
Q. エラーが出たら、まず何をすればいい？
A. claude doctor を実行してください。インストール・設定・MCP・コンテキストを一括チェックできます。続けて /status（今の認証）と /context（何がコンテキストを食っているか）を見れば、認証系・コンテキスト系・接続系のどれかが大抵切り分けられます。
Q. レート制限にすぐ当たります。どうすれば？
A. Claude Code の1ターンにはファイルの中身やツール呼び出しが載るため、公式ドキュメントも1回のデバッグで1日分のチャットを超えることがあるとしており、体感より早く当たります。/usage で上限とリセット時刻を確認し、/model で軽いモデルに、/compact で履歴を圧縮、不要なMCPを無効化。それでも足りなければ上位プラン（Max等）や追加クレジットを検討してください。
Q. 「Invalid API key」なのにキーは合っているはずです。
A. 環境変数の古い ANTHROPIC_API_KEY がサブスクリプションを上書きしているのが定番原因です。env | grep ANTHROPIC で確認し、unset ANTHROPIC_API_KEY（シェル設定ファイルからも削除）してから /login、/status で確認してください。
Q. 社内ネットワークで繋がりません。
A. まず curl -I https://api.anthropic.com で疎通確認を。プロキシ環境なら HTTPS_PROXY を、TLS検査がある環境なら NODE_EXTRA_CA_CERTS にCA証明書を設定します。NODE_TLS_REJECT_UNAUTHORIZED=0 は危険なので使わないでください。api.anthropic.com の許可をIT部門に依頼するのが本筋です。
Q. いろいろ試しても直りません。最後の手は？
A. claude update で最新版に更新してください。Claude Code は更新が速く、既知バグは版を上げるだけで直ることが多いです。それでもダメなら /feedback で会話ログ付きでAnthropicに報告するのが確実です。
