Claude Codeのエラー・困りごと一覧｜自社で実際に踏んだ症状と直し方の早見表【2026年】

Claude Codeのエラーは、ログイン、使用量の上限、会話の長さ、通信の4系統でほぼ引けます。迷ったら、まずClaude Codeの中で /doctor を実行してください。この記事は、症状から直し方を引く早見表と、僕の会社が実際に踏んだエラーの記録をまとめた一覧です。各症状の詳しい手順は、個別の記事に案内します。

Claude Codeのエラー一覧｜症状→原因→直し方の早見表

2026年10月時点の公式のエラー一覧と、当社の作業記録から、よく出るものを表にしました。エラー文は画面に出る英語のままです。Claude Codeは、一時的な失敗なら最大10回まで自動で再試行してからエラーを出します。つまり、エラーが表示された時点で、自動の再試行はもう終わっています。

ここで出てくる言葉を2つ定義しておきます。PATHとは、ターミナルが「打たれたコマンドの本体をどのフォルダから探すか」を決めている一覧のことです。コンテキストとは、Claudeが1回の応答を作るときに読み込む、会話の履歴やファイルの中身をすべて合わせた情報の量のことです。

起動・ログインのエラー（command not found: claude・401・API キーの上書き）

インストールは終わったのに claude が動かない場合、多くはPATHの問題です。ログイン後に401や400が出る場合は、認証情報が切れているか、別の認証方法が優先されています。

公式の手順では、インストーラーはMacとLinuxでは ~/.local/bin/claude に本体を置きます。ここがPATHに入っていないと、Macでは zsh: command not found: claude と出ます。対処は次の順です。

1. echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc でPATHに足す（bashなら ~/.bashrc）
2. ターミナルを開き直す（インストールした画面は古いPATHのまま）
3. それでも動かなければ claude doctor で点検する

インストールの全体の流れはClaude Codeの使い方（インストールから最初の1週間まで）にまとめています。

ログインまわりは、Not logged in · Please run /login と Login expired · Please run /login なら /login だけで直ります。原因が分からないときは、/logout → Claude Codeを閉じる → claude で起動し直してログイン、が公式の「ログインのやり直し」です。

見落としやすいのが、サブスクで契約しているのに API Error: 400 ... "This organization has been disabled" と出るケースです。公式ドキュメントによると、昔の仕事や別の案件で設定した ANTHROPIC_API_KEY がシェルの設定ファイルに残っていて、サブスクのログインより優先されているのが原因です。unset ANTHROPIC_API_KEY で外して起動し、~/.zshrc などから export ANTHROPIC_API_KEY=... の行を消します。どの認証で動いているかは /status で確かめられます。キーが残っていると請求がAPIの従量課金になる点は、Claude Codeの料金と使用量上限の実測で詳しく書きました。

上限と混雑のエラー（You've hit your session limit・529 Overloaded・Request timed out）

この3つは見た目が似ていますが、意味がまったく違います。You've hit your ... limit は自分の使用量の上限、529 Overloaded はAPI全体の混雑、Request timed out は応答が10分以内に返らなかったことを示します。上限だけが「待つかお金を払う」しかない種類です。

使用量上限とは、ProやMaxのプランに設定された、5時間ごとと1週間ごとに使える量の天井のことです。公式のエラー一覧によると、5時間枠と週次枠は全モデル共通なので、モデルを替えても戻りません。一方、You've hit your Opus limit のようなモデル系統ごとの上限は、/model で系統の違うモデルに替えれば続けられます。残りと次のリセット時刻は /usage で見られます。

API Error: Repeated 529 Overloaded errors について、公式のエラー一覧は、使用量の上限ではなく枠にも数えないと説明しています。混雑はモデルごとに数えられるため、数分待つか /model で別のモデルに替えるのが対処です。Request timed out は、既定の待ち時間10分を超えたときに出ます。送り直して直らず、回線やプロキシが遅い環境なら API_TIMEOUT_MS を延ばします。

裏方で実際に起きた例：週次上限で検品が全部止まり、モデルを替えてやり直した

2026年9月29日、社内で開発中のツール（名前と中身はまだ伏せます）の調査と検品を、最上位のFable 5.1（思考の深さhigh）で並行して回していました。途中でFableの週次上限に達し、複数の調査、それらの統合、検品、試作の独立検品がまとめて失敗しました。

その後、同じ入力のままOpus（high）に切り替えて最初からやり直し、すべて完了しています。このとき決めたのは「上限が戻ったら、リリース前の最終チェックのような重要な検品だけはFableでやり直す」というルールです。モデル系統ごとの上限なら、系統を替えれば止まった作業を続けられる、という公式の説明どおりの動きでした。

止まった作業を後から見つけにくい問題は、Claude Codeが途中で止まる・固まる時の切り分けで4種類に分けて書いています。

会話が長すぎるエラー（Prompt is too long・Autocompact is thrashing）

Prompt is too long は、会話と読み込んだファイルの合計が、モデルの読める量を超えたときに出ます。/compact で古いやり取りを要約して縮めるか、/clear で新しい会話にすれば直ります。話題が変わったのに同じ会話を使い続けるのが、一番多い原因です。

公式のエラー一覧が挙げる対処のうち、主なものは次の4つです。

1. /context で、どのやり取りがどれだけ容量を使っているかを見る
2. /compact で古いやり取りを要約して縮める
3. 前の会話が要らなければ /clear で新しい会話にする
4. /model で、より大きなコンテキストウィンドウを持つモデル（[1m] の付いた拡張版）に替える

もう1つ、Autocompact is thrashing: the context refilled to the limit... というエラーがあります。自動の要約自体は成功したのに、大きなファイルやツールの出力が何度もすぐに会話を埋め直したため、Claude Codeが無駄な再試行を止めた、という意味です。ファイルを行の範囲で小分けに読ませる、大きな作業をサブエージェントに分ける、/clear する、のどれかで抜けられます。

当社では、案件が変わったら /clear で会話を分ける「1セッション1案件」をルールにしています。会話を伸ばし続けると、このエラーの手前で使用量も大きく減っていたからです。この実測は料金の記事に載せています。

エラーは出ないのに困る症状（止まる・許可・英語・URL・MCP）

困りごとの半分は、エラー文が出ません。止まったまま動かない、毎回許可を聞かれる、英語で返ってくる、URLが読めない、貼り付けた画像が見つからない、入れたプラグインが出てこない、MCPが見つからない、の7つは当社でも実際に起きました。ここは要点だけ書き、詳しい手順は個別の記事に任せます。

• 宣言だけで止まる: 「〜します」と書いたまま、実行せずに入力待ちに戻る症状です。社内では2026年7月に繰り返し起き、「やると言ったら同じ応答の中で着手する」「空振りしたら聞き返さず自分でやり直す」を全セッション共通のルールにしました。切り分け方はClaude Codeが途中で止まる時の4つの原因へ。
• 毎回「許可しますか」と聞かれる: && でつないだコマンドや cd を混ぜたコマンドは、許可ルールと形が合わずに止まります。設定はClaude Codeで毎回許可を聞かれる原因と設定へ。
• 英語で返ってくる: 社内で開発中のツールの作業セッションでも、英語のツール出力を読んだ直後の報告で、5回以上英語に戻りました。止め方はClaude Codeが英語で返してくる時の直し方へ。
• URLが読めない・403: 1回の失敗で「読めませんでした」と止まらせず、読む手段を段階的に上げます。手順はClaude CodeでURLが読めない・WebFetchが403になる時の対処へ。
• 貼り付けた画像が見つからない: チャットに貼った画像は、ダウンロードフォルダには保存されません。当社でも2026年7月に、AIが担当者へ再送を頼みかけました。探す場所と復元の手順はClaude Codeに貼り付けた画像の保存場所と取り出し方へ。
• 入れたプラグインが出てこない・入れてから重い: シェルで入れたプラグインは、次の起動か /reload-plugins まで、動いているセッションには読み込まれません。確認の順番はClaude Codeのプラグインが反映されない・入れたら重くなった時の確認手順へ。
• ブラウザ操作で日本語だけ入らない: Claude in ChromeにGoogleスプレッドシートを操作させると、英数字は入るのに日本語だけセルに入らないことがあります。エラーが出ないので気づきにくい症状です。貼り付けに切り替える手順はClaude in Chromeでスプレッドシートに日本語が入力できない時の回避策へ。
• ブラウザ操作でファイルを上げられない: Claude in Chromeにページのアップロード欄へファイルを付けさせようとして、断られることがあります。Claude Codeの版と、公式が挙げる4つの原因を順に確かめます。確認の手順はClaude in Chromeでファイルをアップロードできない時の原因と対処へ。
• アプリ内ブラウザで毎回ログインを求められる: デスクトップアプリのBrowserペインは普段のブラウザとは別の環境で、保存済みのログインがありません。当社でも2026年8月に、前のセッションで済ませたログインが次のセッションに残りませんでした。確かめる設定と運用はClaude Codeのアプリ内ブラウザでログインが保持されない時の設定と運用へ。
• セッション名が英語になる・一覧で見分けにくい: 名前を付けていないセッションには、最初の指示を要約した題名が自動で付きます。当社は2026年7月に名前の形を1つに決め、過去の97件を付け直しました。変え方と付け方はClaude Codeのセッション名を変更する方法と名前の付け方へ。
• 一括削除で残すはずのファイルまで消えた: Macのzshは、空白で区切ったリストを変数に入れてforで回しても、分割せず1語として扱います。当社でも2026年9月に、6件残すはずのテスト用の下書き41件が全部消えました。エラーは出ません。原因と直し方はzshのforで変数が分割されない原因と直し方へ。

MCPが別のフォルダで見つからない

MCPとは、Claude Codeに外部のツールやサービスをつなぐための共通の接続規格です。公式ドキュメントでは、claude mcp add で登録したサーバーの既定のスコープは local で、追加したプロジェクトの中でしか読み込まれません。

当社は動画編集ソフトの下書きを自動で作るMCPを入れたとき、別のフォルダでClaude Codeを開いたらMCPが無い、という状態になりました。claude mcp get <名前> の Scope: 行で local になっているのを確かめ、claude mcp remove <名前> -s local で外してから、claude mcp add --scope user ... で入れ直して再起動したら直りました。それ以来、社内の手順書では「登録は必ずuser」にしています。Macを買い替えたあとにMCPや自動メモリが消えたように見える場合は、Claude Codeを新しいMacに移行する手順を確認してください。この自動化の全体はCapCutの下書きをClaude Codeで自動化した実録に書きました。GA4などGoogle CloudのデータをMCPでつなぐときに鍵が作れない場合は、サービスアカウントの鍵が作れない時（iam.disableServiceAccountKeyCreation）の対処を見てください。

Claude Codeで作ったツール側で出たエラー（onnxruntime・ElevenLabs・Whisper）

Claude Codeに作らせたツールや、使わせた外部サービスの側でもエラーは出ます。どれも単独の記事にするほどの量はないので、ここに実際の表示と直し方だけ残します。いずれも、Claude Codeの設定ではなく、使ったライブラリやサービスの仕様が原因でした。

ブラウザの推論ツールは2026年9月11日、取引先向けに作った写真処理の小道具で踏みました。HEICの件は、Macで作った検証用のHEICでは古いライブラリでも読めてしまい、実機で撮った写真で初めて分かりました。検証には実機のデータを使う、が教訓です。

音声生成の件は2026年10月1日です。生成の途中で 401 が返り、認証が切れたのかと疑いましたが、実際はキーごとの上限でした。いまはキーの上限を外し、生成スクリプトが25本ごとに実際の残高を確かめてから進むようにしています。

再発防止と、業務で使うときの注意

エラーは「どれが出たか」より「次に同じ止まり方をしない仕組み」が大事です。当社では、点検は /doctor、上限は /usage、会話は1案件1セッション、失敗の記録はルールのファイルへ、の4つで回しています。

1. 最初に /doctor: 公式ドキュメントでは、インストール・設定・拡張機能・コンテキストの使用量をまとめて点検できます。起動しないときは claude doctor、MCPの状態は /mcp です。
2. 上限は公式の数字で見る: 残量は /usage で確かめます。当社は自前の計算で残量を判断して、枠が半分残っているのに作業を止めた失敗があります。公式の%を画面の下に出しっぱなしにする手順は、Claude Codeの使用量をステータスラインに常時表示する方法にまとめました。
3. 会話を伸ばさない: 案件が変わったら /clear。続きは引き継ぎメモを書かせ、新しい会話で読ませます。
4. 起きたことをルールに書く: 同じエラーを2回踏んだら、社内ルールのファイルに1行足します。宣言だけで止まる件も、MCPのスコープの件も、こうしてルールになりました。

業務で使うときの注意も書いておきます。サポートに出す診断用のファイルには注意が要ります。/heapdump が書き出す .heapsnapshot には、会話の全文や認証情報が含まれると公式が警告しています。公開の場に貼らないでください。エラーの相談のためにClaudeの会話を共有リンクにした場合も、リンクを知っていれば誰でも見られます。もし検索に出てしまったときの止め方は、Claudeの共有リンクが検索に出る時の対処にまとめました。また、エラーを直すために許可ルールを広げすぎると、無人で動かすときに危険な操作まで通ってしまいます。直すときは「何を許すか」を1つずつ決めるのが安全です。

アカウントや請求の問題は、Claude Codeの中では直せません。claude.aiにログインし、左下の自分のイニシャルから「Get help」を選ぶのが公式の窓口です。こうした社内ルールの作り方まで含めて、ウラカタのサービス一覧でAI活用の立ち上げを支援しています。