目次
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。繰り返すなら端末の時計ずれ・キーチェーンロックを確認 |
| Invalid API key | 古い ANTHROPIC_API_KEY が残存 | env | grep ANTHROPIC で確認 → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired | 他所でログアウト／管理者が無効化 | /logout → /login。時計ずれも疑う |
| This organization has been disabled | 無効化された組織のAPIキーが上書き | シェル設定（.zshrc等）からキーを削除 → /login → /status で確認 |
| 403 Forbidden（ログイン後） | サブスク失効・ロール不足・プロキシ干渉 | サブスク状態とConsoleロールを確認。プロキシ環境は HTTPS_PROXY を設定 |
鉄則：「環境変数のAPIキー」はサブスクリプションログインより優先される。会社のCI用などに ANTHROPIC_API_KEY を設定したまま忘れていると、個人のPro/Max契約が無視される。まず /status で「今どの資格情報で動いているか」を見るのが正解だ。
3. 使用量・レート制限系（最頻出）
Claude Code で最も多い相談がこれ。Claude Code はチャットの10〜100倍のトークンを消費する（多ターン会話・巨大コンテキスト・ツール往復のため）ので、体感より早く上限に当たる。
「制限に当たった」ときの3手
/usage で上限とリセット時刻、/status で資格情報を確認/model で軽いモデルに、/compact で履歴圧縮、不要MCPを無効化
注意：「Server is temporarily limiting requests」はプラン上限ではなく一時的なサーバー側スロットル。少し待って再試行でOK。
プラン上限（session/weekly）とは別物なので混同しない。
補足：「429 / Request rejected」はAPIキー・ワークスペースのレート超過。「Credit balance is too low」はConsoleのプリペイド残高切れ（請求設定でチャージ or サブスクに切替）。なお2026年3月頃、Maxユーザーで「5時間枠が異様に速く尽きる」報告が技術メディア・公式リポジトリのIssueで相次いだ（バグ疑い）。頻発するなら最新版更新と /usage での実測、必要なら /feedback 報告を。トークン節約の体系的な方法は AIトークン節約術・Claude Codeのトークン節約 も参照。
4. コンテキスト・トークン系
長い会議や巨大ファイルを扱うと出るのがこれ。
| 症状 | 原因 | 対処 |
|---|---|---|
| Prompt is too long | 会話＋ファイルがコンテキスト窓を超過 | /compact（要約）・/clear（リセット）・/context で内訳確認・不要MCPを /mcp で無効化 |
| Error during compaction: Conversation too long | 圧縮の出力分の空きが足りない | Esc 2回で数ターン巻き戻してから /compact。ダメなら /clear |
| Auto-compact is thrashing | 圧縮直後に巨大出力で即再充填 | 大きいファイルは行範囲で分割して読む／/compact keep only ○○ で焦点指定／サブエージェントに分離 |
コツは 「巨大ファイルを丸ごと読ませない」こと。ログやデータは行範囲を指定して小分けに渡す。コンテキストウィンドウの考え方を押さえると、この種のエラーは激減する。
5. サーバー・モデル系
| 症状 | 原因 | 対処 |
|---|---|---|
| 500 Internal server error | Anthropic側の一時障害 | status.claude.com を確認 → 1分後に再試行 |
| 529 Overloaded（連発） | API全体が一時的に高負荷 | 数分待つ。/model でモデルを変えて負荷分散 |
| Request timed out | 既定10分以内に応答が返らない | タスクを小さく分割。低速回線なら API_TIMEOUT_MS を引き上げ |
| model not found / アクセス権なし | モデル名が不正 or 契約に含まれない | /model で選び直し。古い ANTHROPIC_MODEL 環境変数を確認 |
| Opus is not available with Pro plan | 選択モデルがプラン対象外 | /model で利用可能モデルへ。プラン変更直後は /logout→/login で更新 |
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 |
| Multiple claude installations found | npm/Homebrew/native の重複 | 1つに統一。例：npm uninstall -g @anthropic-ai/claude-code |
| 古いバージョン由来の不具合 | 未更新 | claude update（多くのバグが解消する最優先策） |
7. ネットワーク・プロキシ系
社内ネットワークやVPN環境で多い。まず curl -I https://api.anthropic.com で疎通を確認する。
| 症状 | 原因 | 対処 |
|---|---|---|
| Unable to connect / ECONNREFUSED / ETIMEDOUT | 未接続・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 にして対象ドメインを許可 |
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サーバーのタイムアウト | 起動>5秒 等 | MCP_TIMEOUT=10000 claude（ミリ秒）で延長。個別は .mcp.json に "timeout" |
9. 権限・ツール系
「bypassモードなのに許可を求められる」系。deny ルールは allow・bypass より優先されるのが要点。
| 症状 | 原因 | 対処 |
|---|---|---|
| bypassモードでも許可を求められる | deny ルールが優先。危険操作はサーキットブレーカーで常に確認 | /permissions で 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エラー解説。 - プルリクエストのステータスを確認できませんでした：GitHub接続（多くは
gh認証）の問題。gh auth statusから。詳細は PRステータスエラー解説。 - Image was too large / PDF too large：画像は長辺8000px超、PDFは100ページ/32MB超で弾かれる。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 で deny ルール確認 |
| とにかく直したい | claude update（最新版で多くが解消） |
まとめ
Claude Code のエラーは数あれど、初手は claude doctor / /status / /context の3コマンドで原因の切り分け——これでほとんどの問題は前に進む。頻出は 使用量・レート制限／コンテキスト超過／認証切れ／MCP接続失敗の4系統で、それぞれ /usage・/compact・/login・/mcp が一次対処になる。
そして見落としがちな最強の一手が claude update で最新版に保つこと。Claude Code は更新が速く、過去のバグ（thinking blocks 400 など）も版を上げるだけで直ることが多い。「詰まったら、まず診断3コマンド。直らなければ最新版へ」——この型を持っておけば、エラーで時間を溶かすことはなくなる。
関連記事：thinking blocks 400エラー、PRステータス確認エラー、Claude Codeトークン節約、bypassでも許可を求める理由、MCPとは も併読を。
FAQ
Q. エラーが出たら、まず何をすればいい？
A. claude doctor を実行してください。インストール・設定・MCP・コンテキストを一括チェックできます。続けて /status（今の認証）と /context（何がコンテキストを食っているか）を見れば、認証系・コンテキスト系・接続系のどれかが大抵切り分けられます。
Q. レート制限にすぐ当たります。どうすれば？
A. Claude Code はチャットの10〜100倍のトークンを消費するので体感より早く当たります。/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に報告するのが確実です。
