AIコーディングを続けていれば、必ずエラーに出会います。赤い文字が出た瞬間に手が止まる――その時間こそがいちばんの生産性の敵です。でも安心してください。Claude Code をはじめとするAIコーディングツールで遭遇するエラーは、ほとんどが決まったパターンの繰り返しです。種類さえ見分けられれば、対処はほぼ機械的に決まります。この章は、詰まった時にまず開くトラブル・トリアージ（切り分け）の地図です。
「エラーで止まらない」自分になる
🧭 まず1本のまとめ記事。 よくあるエラーを横断的に集めた総まとめが「Claude Code よくあるエラーと対処法まとめ」です。この章は各カテゴリを俯瞰する地図、リンク先の個別記事が具体的なメッセージ例と手順を持ちます。ブックマークして、詰まったらここから辿るのがおすすめです。
エラーは「種類」で切り分ける
対処の第一歩は、「これは何系のエラーか」を見分けることです。原因のレイヤーが違えば、直す場所も違います。細かなメッセージを読み込む前に、まず次の6カテゴリのどれかに当てはめてください。当てはめた時点で、対処の8割は決まります。
そもそも起動しない・コマンドが無い。入口の問題。↓詳しく
ログインできない・認証が切れる。アカウントとの接続。↓詳しく
通信できない・サーバー混雑。経路とサーバー側の問題。↓詳しく
上限に達した・使えない時間。プランと使用量の問題。↓詳しく
長すぎる・詰め込みすぎ。渡した情報量の問題。↓詳しく
拡張・ツール呼び出しが失敗。周辺機能の問題。↓詳しく
💡 見分けのコツ。 エラー文の中のキーワードひとつで当たりがつきます。command not found→①、authentication／login→②、connection／network／529→③、usage limit→④、too long→⑤、MCP／tool→⑥。メッセージを丸ごと読む前に、まずこの単語を探しましょう。
① 導入・起動系 ― コマンドが見つからない
最初の関門は「そもそも起動しない」です。インストールが途中で失敗していたり、パス（PATH）が通っていなかったりで、コマンドを打っても反応しない。ここでつまずくと先へ進めないので、落ち着いて入口を確認します。
症状: claude と打つと「そんなコマンドは無い」と返る。
原因: インストール先にPATHが通っていない、シェルの再読み込みがされていない、インストール自体が未完了。
対処: ターミナルを開き直す／PATHを確認する／再インストールする。順に試せば大抵抜けられます。
症状: インストール中にエラーで止まる／権限（permission）で弾かれる。
原因: Node.jsのバージョンが古い、権限不足、ネットワーク経由でパッケージ取得に失敗。
対処: 前提環境（Node等）を更新し、管理者権限やインストール方法を見直す。企業ネットならプロキシも疑う。
🔧 詳しい手順はこちら。 インストール失敗と command not found の原因切り分けと具体的な直し方は「command not found / インストールエラーの直し方」にまとめてあります。導入でつまずいたら、まず第2章「Claude Codeを始める」の手順どおりに入れ直すのが最短です。
② ログイン・認証系 ― 認証が通らない
起動はするのに、ログインや認証で弾かれるパターンです。ブラウザ認証がうまくいかない、しばらく使っていたら急にサインアウトされた、といった形で現れます。アカウントとツールの「握手」がずれている状態です。
症状: ログイン画面から進めない／認証エラーで弾かれる／認証用のブラウザが開かない。
原因: 認証トークンの期限切れ・破損、リダイレクトの失敗、プランや対象アカウントの取り違え、時刻ずれ。
対処: 一度サインアウトして入れ直す／保存された認証情報をクリアして再認証／正しいアカウントか確認。
「認証エラー」に見えて、実はプランや契約の対象が違うだけのこともあります。
複数アカウントを使い分けている人は、ログイン中のアカウントとプランの種類をまず確認しましょう。会社支給と個人用の混在は典型的な落とし穴です。
🔑 詳しい手順はこちら。 認証が通らない時の再ログイン・トークン再取得の手順は「ログイン・認証エラーの対処法」にあります。多くは再サインインで解決しますが、直らない場合はネットワーク側（③）も疑ってください。
③ 接続・ネットワーク系 ― つながらない・混雑
ここは原因が「自分側」と「サーバー側」の2つに分かれるので、切り分けが肝心です。自分の回線やプロキシが塞いでいるのか、それともサーバーが一時的に混んでいるのか。前者は自分で直せ、後者は待つ・軽くするのが基本方針になります。
症状: 接続できない・タイムアウトする・通信が途中で切れる。
原因: ネット回線の不調、社内プロキシやファイアウォールによる遮断、VPN、証明書やDNSの問題。
対処: 別回線で試す／VPNを切る／プロキシ設定を見直す。会社ネットなら管理者に許可対象を確認。
症状: overloaded や 5xx が返る。自分の設定は正しいのに失敗する。
原因: サーバー側の一時的な高負荷・障害。あなたのコードや設定のせいではない。
対処: 少し待って再試行／混雑する時間帯を避ける／障害情報（ステータスページ）を確認。
⚠️ 切り分けの目安。 他のサイトやサービスは正常なのにAIツールだけ落ちるなら、サーバー側（529/500）の可能性が高く、対処は「待つ」。他の通信も不安定なら自分側（回線・プロキシ・VPN）です。詳しくは「接続・ネットワーク・プロキシエラー」と「529 overloaded / 500 エラーの意味と対処」を参照してください。
④ 利用制限系 ― 上限に達した
エラーではなく「制限に達したので今は使えない」という通知です。プランごとに一定時間あたり・一週間あたりの使用量に上限があり、そこに触れると一時的に止まります。故障ではないので、直そうとするより使い方とプランで調整するのが正解です。
症状: 「利用上限に達しました」と表示され、一定時間まで使えなくなる。
原因: プランの使用量上限に到達。大きなタスクや長い会話を短時間に回すと早く届く。
対処: リセットまで待つ／会話を分割して軽く使う／必要ならプランを見直す。
症状: 週の途中で上限に達する／リセットの時期が思ったより早い・遅い気がする。
原因: 週次の枠は初回利用を起点に数えるなど、カレンダー週とは限らない仕組みのことがある。
対処: リセットの数え方を正しく理解し、消費の大きい作業を計画的に配分する。
📊 上限は「管理」でほぼ避けられる。 上限の意味と待ち時間の考え方は「利用上限に達した時の対処」、週次リセットの数え方は「週次上限が早くリセットされる仕組み」で確認できます。そもそも上限に触れにくい使い方は第7章「コストと効率」でまとめて扱います。
⑤ 入力・コンテキスト系 ― 長すぎる
AIが一度に扱える情報量（コンテキスト）には上限があります。会話が長引いたり、巨大なファイルを丸ごと渡したりすると、「入力が長すぎる」と拒否されます。これは詰め込みすぎのサインなので、渡す量を減らす・区切るのが対処です。
症状: 「入力が長すぎる」と出て、指示が実行されない。
原因: 会話履歴の蓄積、巨大ファイルや大量ファイルの読み込み、貼り付けたログが長すぎる。
対処: 会話を整理・要約する／新しい会話を始める／必要な範囲だけを渡す／タスクを小さく分ける。
症状: 思考（thinking）まわりの処理でエラーが出て応答が中断する。
原因: 会話状態の不整合や、履歴が絡んだ内部的な処理の食い違い。長い会話で起きやすい。
対処: 会話を新しく始め直す／該当のやり取りを分ける。多くはリフレッシュで解消。
✂️ 「長い」は設計で防げる。 具体的な減らし方は「prompt is too long の対処法」、thinking 周辺の不具合は「thinking block エラーの対処」にあります。そもそもタスクを小さく区切るのが根本策で、これは第4章「上手に頼む」で扱った指示の出し方と直結します。
⑥ MCP・ツール系 ― 拡張がうまく動かない
MCP（外部ツール連携）やツール呼び出しは、Claude Code 本体は正常でも、周辺の拡張だけが失敗することがあります。本体のエラーと切り分けて考えるのがコツです。まず「拡張を外しても再現するか」を確かめると、原因の切り分けが一気に進みます。
症状: MCPサーバーに接続できない／連携ツールが一覧に出ない・反応しない。
原因: 設定ファイルの記述ミス、サーバーの起動失敗、パスや依存関係の不足、認証情報の不備。
対処: 設定を見直す／サーバーを単体で起動確認／一度外して本体だけで動くか切り分け。
症状: ツールの呼び出しが失敗する／呼び出し結果の受け渡しで止まる。
原因: ツール定義や引数の不整合、会話状態のずれ、連携先の一時的な不調。
対処: 会話を仕切り直す／該当ツールを一時的に無効化して切り分け／連携先の状態を確認。
症状: PR（プルリクエスト）まわりのステータスチェックでエラーになる。
原因: 連携するCIやチェックの設定・権限、外部サービス側の状態が絡むことが多い。
対処: チェック側の設定・権限を確認／再実行／外部サービスの状態を確認。
🧩 拡張系は「外して切り分け」。 MCP接続の直し方は「MCPサーバー接続エラーの対処」、ツール呼び出しの不具合は「ツール呼び出しエラーの対処」、PRチェック関連は「PRステータスチェックエラーの対処」を参照。拡張機能そのものの使い方は第6章「拡張機能を使う」で扱います。
詰まった時の抜け方 ― 万能の5手
原因がすぐに特定できない時でも、まず試すべき「万能の一手」があります。多くのエラーは、状態のリフレッシュや、負荷を軽くするだけで消えます。上のカテゴリで当たりがつかない時は、この5つを上から順に試してください。
ツールとターミナルを閉じて開き直す。一時的な状態の乱れは、これだけで大半が消えます。まず疑うべき最初の一手。
長い会話は不整合の温床。新しい会話を始めるか、履歴を要約・整理（/compact的な発想）して身軽にする。⑤に効く。
一度に大きく頼まず、タスクを小さなステップに割る。長すぎ・重すぎ由来のエラーは、これで根本から避けられる。
529/500や混雑は時間が解決する。数分待って再実行。ステータスページで障害情報も確認する。③④に効く。
どうしても分からなければ、エラー文を丸ごとAIや検索に渡す。この章の総まとめ記事と照らせば、大抵は既知のパターンに当たる。
🧯 慌てないことが最大の対処。 エラーは「壊れた」合図ではなく、「ここを直せ」というヒントです。カテゴリを見分け、上の5手を試し、それでも駄目なら個別記事へ。この流れさえ身につけば、赤い文字はもう怖くありません。
- エラーはまず6カテゴリに切り分ける（導入・認証・接続・利用制限・コンテキスト・MCP/ツール）。キーワードひとつで当たりがつく。
- 各カテゴリは症状→原因→対処がほぼ決まり型。529/500などサーバー側は「待つ」、長すぎは「分ける・整理する」が基本。
- 原因不明でも万能の5手（再起動・会話を仕切り直す・小さく分ける・待って再試行・エラー文をそのまま渡す）で大半を抜けられる。
- 具体的な手順は総まとめ記事と各個別記事へ。上限管理は第7章、拡張は第6章で深掘り。
エラーとの付き合い方が分かれば、AIコーディングは一気に前へ進みます。次は、Claude Code の能力そのものを広げる番です。次の第6章「拡張機能を使う」で、hooks・plugins・subagents・MCP を使って相棒をさらに強くしていきましょう。