Claude Codeのエラー対処法｜動かない・使えないときの原因と直し方

Q: エラーが出ると、会話や作業は消えますか？

固まって再起動した場合も、会話は消えません。同じフォルダでclaude --resumeを実行すると、前の続きから再開できます。

Q: Claude Codeを再インストールすれば直りますか？

再インストールが必要なのは、command not foundや、複数のインストールが混在している場合など、インストール自体の問題のときだけです。500・529・上限・ログインのエラーは、再インストールしても直りません。 インストールが混在しているかは、which -a claude（Windowsではwhere.exe claude）で確認できます。複数見つかったら、1つだけ残します。

Q: エラーを予防する方法はありますか？

完全には防げませんが、次の3つでエラーの種類ごとに減らせます。 会話が長くなったら、早めに/compactをかける（Prompt is too longの予防） 使っていないMCPサーバーは無効にしておく（容量の節約） 使用量を/usageや ccusage で定期的に確認し、上限の手前で作業の区切りをつける 設定まわりの整え方は、 Claude Codeの初期設定ガイド｜settings.jsonの場所と権限の書き方 にまとめています。 https://ai-hacks.jp/claude-code-settings/

Q: 自分では直せないエラーは、どこに相談すればいいですか？

公式ドキュメントでは、次の順で案内されています。 /doctorで設定を確認し、/mcpでMCPの状態を確認する Claude Code内の/feedbackでAnthropicに報告する GitHubのリポジトリで、既知の問題を探す Claude Codeに、機能について直接質問する（ドキュメントを参照できます） アカウントや請求のトラブルは、Anthropicのサポートに連絡します。

2026年10月8日

当ページのリンクには広告が含まれている場合があります。

こんにちは、ハックです。AIを相棒に、非エンジニアから今では様々なツールやアプリを開発をしている一人社長です。

「Claude Codeが急に動かなくなった」「英語のエラーが出て、何が起きているのか分からない」

作業の途中でこうなると、手が止まってしまいますよね（汗）

結論から言うと、Claude Codeのエラーは大抵の場合、Anthropic側の問題（待てば直る）・自分の利用上限（待つか切り替える）・自分の環境（自分で直す）の3つに分かれます。

この記事では、画面に出るエラー文ごとに、その3つのどれなのかと、打つコマンドを順番に整理します。

ハック（Hack）

僕の場合、よくあるエラーは、MCPの接続エラーと、利用上限（session limit・weekly limit）かな。（制限をエラーというには微妙だけど）逆に、サーバー側のエラーはほとんど経験ないかなぁ〜。

駆動愛

エラーが出たら、まず画面のエラー文を1行そのままコピーしてください。この記事の見出しは、エラー文の英語をそのまま使っているので、コピーした文をページ内検索にかけると、該当の項目に飛べます。

🧭 読み終えたとき、あなたはこうなっています

画面に出たエラー文を見て、Anthropic側の障害・利用上限・自分の環境のどれなのかを判断できる
500・529・429・401・Prompt is too longなど、よく出るエラーごとに、待つ・直す・切り替えるのどれをやるかがわかる
/status・/doctor・curlなど、原因を調べるために打つコマンドがわかる

⚠️ この記事の信頼性について

筆者（ハック）はプログラミング未経験の状態からAI駆動開発を始め、現在はClaude Codeを日常的に使いながらツールやアプリを開発しています。エラー文と対処法はAnthropic公式ドキュメント（最終確認：2026年10月1日）の原文に基づいています。MCPの接続エラーと利用上限への対応は、筆者が実際に体験した内容です。バージョンによってエラーメッセージの文言は変わることがあります。

Claude Codeのエラーとは？エラー文の見方

Claude Codeのエラーは、画面に出た英語の1行が、そのまま原因の手がかりになります。エラー文の頭にある番号や言葉を見れば、どこで問題が起きているかが分かる作りになっています。

まず覚えておきたいのは、次の3分類です。

分類	代表的なエラー文	やること
Anthropic側の問題	`API Error: 500 Internal server error`／`API Error: Repeated 529 Overloaded errors`	待つ・別のモデルに切り替える
自分の利用上限	`You've hit your session limit`／`You've hit your weekly limit`	リセットまで待つ・追加購入・他のツールに切り替える
自分の環境	`Not logged in · Please run /login`／`Unable to connect to API`／`command not found: claude`	設定やコマンドで直す

この表のうち、上2つは自分では直せません。直せるのは3行目だけなので、最初に「どの行か」を決めるのが最短ルートです。

また、Claude Codeはエラーを表示する前に、一時的な障害を最大10回まで自動でやり直しています。エラーが画面に出た時点で、すでにリトライは終わっているということです。

やり直している最中は、画面にRetrying in Ns · attempt x/y（N秒後に再試行・x回目/最大y回）というカウントダウンが出ます。これは故障ではなく、待っている状態です。

💡 補足解説：リトライ（自動再試行）とは

リトライとは、通信が失敗したときに、同じ依頼を自動でもう一度送り直す仕組みです。Claude Codeでは、待ち時間を少しずつ長くしながら（指数バックオフ）やり直します。カウントダウンの間は、何もしなくて大丈夫です。

Claude Codeの「API Error」の読み方

エラー文の先頭にAPI Error:と付いているものは、Claude Codeが裏側でAnthropicのAPI（Claudeの頭脳につながる窓口）にお願いを送ったときに、返事としてエラーが返ってきたという意味です。

その後ろの数字が、状況を表しています。

番号	意味	この記事の説明先
500・502など5から始まる番号	Anthropic側（サーバー）の予期しない障害	500・529の章
529	Anthropic側の容量が一時的に満杯	500・529の章
429	リクエストの制限（設定されたレート制限など）	429・利用上限の章
401	ログイン情報が拒否された	ログインエラーの章
400	リクエストの内容に問題がある	接続エラーの章

5から始まる番号は、Anthropic側の問題です。公式ドキュメントには「5xx は API 内の予期しない障害を示しています。これはお客様のプロンプト、設定、またはアカウントが原因ではありません。」と明記されています。

自分のせいではないと分かるだけで、無駄な設定いじりをしなくて済みます。

Claude Codeのエラー状況を確認する方法（status.claude.com）

「今、Anthropic側で障害が起きているのか」を確かめる場所が、status.claude.com（Anthropicの公式ステータスページ）です。

Claude Codeが動かないときの対処法

「エラー文も出ないまま固まった」「なんとなく動きがおかしい」というときは、定番の方法を試してみるのが近道です。この章では、どのエラーにも共通して使える調べ方を紹介します。

画面が固まって反応しないときは、まず次の順番で試します。

Ctrl+Cを押して、今の操作をキャンセルする
反応しなければ、ターミナルを閉じて開き直す
同じフォルダでclaude --resumeを実行して、前の会話を再開する

claude --resume

再起動しても、それまでの会話の記録は失われません。claude --resumeで前の続きから再開できるので、固まったときは思い切って一旦閉じてしまっても大丈夫です。

動作が重い場合は、会話（コンテキスト）が長くなりすぎている可能性があります。/compactで会話を要約して軽くすると改善することがあります（詳しくは後の章で説明します）。

Claude Codeのエラーログを見る（/status・/usage）

Claude Code自体が何を認識しているかは、対話画面で次の2つを打つと分かります。

/status

/statusは、今のログイン状態・使っている認証情報・読み込んだ設定ファイルなどを表示します。ログインのエラーや429のエラーでは、まずこれを打つように公式ドキュメントも案内しています。

/usage

/usageは、プランの利用上限と、リセットされる時刻を表示します。「上限に当たったのか、別の問題なのか」を切り分けるときに使います。

設定ファイルの読み込み状況の確認方法は、Claude Codeの初期設定ガイド｜settings.jsonの場所と権限の書き方でも解説しています。

claude doctorで診断する

原因が分からないときの万能コマンドが、/doctorです。

/doctor

/doctorは、インストール・設定・拡張機能・コンテキスト（会話の記憶量）の使用状況を自動でチェックして、直せるものは修正案まで出してくれます。

claudeのコマンドがそもそも起動しないときは、対話画面に入れません。その場合は、ターミナル（シェル）から次のように打ちます。

claude doctor

この2つのコマンドは、名前が同じで場所だけが違います。対話画面の中なら/doctor、ターミナルから打つならclaude doctorと覚えれば迷いません。

MCP（外部ツールとつなぐ仕組み）の状態を見たいときは/mcpを打ちます。

/mcp

プラグイン・MCPサーバー・フックなどの追加設定が原因かもしれないと疑うときは、claude --safe-modeで起動します。セッション中のカスタマイズがすべて無効になるので、それで動くなら原因は追加設定側だと絞り込めます。

エラーが発生しましたと出たらエラー文をClaude Codeに聞く

ハック（Hack）

エラーが出たとき、僕はエラー文をそのままClaude Codeに貼って「これ何が起きてる？どう直す？」と聞くことがよくあります。Claude Codeは自分のドキュメントを参照できるので、英語のエラー文でも原因と直し方を日本語で返してくれます。

やり方は簡単で、画面のエラー文をコピーして、次のように貼るだけです。

💡 補足解説：エラー文の聞き方（コピペ用）

次のエラーが出ました。原因と、僕が打つべきコマンドを教えてください。（ここにエラー文を貼る）

コツは、エラー文を要約せず、そのまま貼ることです。番号や括弧内のコード（ECONNRESETなど）が、原因を絞る手がかりになるからです。

ただし、Claude Code自体が動かなくなっているときは、聞く相手がいません。その場合は、ブラウザ版のClaudeにエラー文を貼って聞くか、この記事の該当箇所を開いてください。

自分で設定したフック（hooks）が原因で、操作が止まって見えることもあります。フックの仕組みと、止めたいときの外し方は、以下の記事でまとめています。

Claude Codeの500エラー・529エラーの対処法

500と529は、どちらもAnthropic側の問題で、自分の設定やアカウントは関係ありません。慌てて設定を変えたり、再インストールしたりする必要はありません。

違いは、原因が「予期しない障害」か「アクセス集中による満杯」かです。それぞれ、エラー文と対処を見ていきます。

API Error: 500（サーバーエラー）

500のエラー文は、次のように表示されます。

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

意味は「これはサーバー側の問題で、たいてい一時的です。少し待ってやり直してください。続くならステータスページを確認してください」です。

対処法は、公式ドキュメントに次の3つが載っています。

status.claude.comで、進行中のインシデントがないかを確認する
1分待ってから、もう一度メッセージを送る
インシデントが出ていないのにエラーが続くなら、/feedbackで報告する

2番目のやり直しでは、元のメッセージは会話に残っているので、長いプロンプトを貼り直す必要はありません。try againと入力するだけで再送できます。

プロキシ（通信の中継役）などが間に入っている環境では、API Error: 502 Bad Gatewayのように、番号とページのタイトルが表示されることもあります。5から始まる番号なら、考え方は同じです。

API Error: 529 Overloaded

529のエラー文は、次のように表示されます。

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Overloadedは「過負荷」、at capacityは「容量がいっぱい」という意味です。全ユーザーのアクセスが集中して、APIが一時的に受け付けきれない状態です。

ここで大事なのは、公式ドキュメントの次の一文です。

「529 はお客様の使用制限ではなく、クォータに対してカウントされません。」

つまり、529が出ても、自分の利用枠が減ったわけではありません。上限（session limit）に当たったのとは、まったく別の話です。

対処法は、次の3つです。

status.claude.comで、容量に関する通知が出ていないか確認する
数分待ってから、もう一度試す
/modelを実行して、別のモデルに切り替えて作業を続ける

3つ目は、容量がモデルごとに管理されているためです。たとえば、Opusが混んでいるときにSonnetへ切り替えれば、作業を続けられることがあります。

Claude Codeは、特定のモデルの負荷が高いとき、Opus is experiencing high load, please use /model to switch to Sonnetのように、切り替えを促すメッセージを出します。

/model

500と529以外にも、Request timed out（応答が時間内に返らなかった）というエラーがあります。デフォルトのタイムアウトは10分です。再送するか、作業を小さいプロンプトに分けると通りやすくなります。

Claude Codeが使えない：429エラー・利用上限の対処法

「Claude Codeが使えない」と検索する人の多くは、この章のエラーに当たっています。エラー文が似ていても、原因は3種類に分かれるので、ここで見分けます。

エラー文	何が起きているか	直す？待つ？
`You've hit your session limit · resets 3:45pm`	自分のプランの利用上限に達した	待つ・追加購入・切り替え
`API Error: Server is temporarily limiting requests (not your usage limit)`	サーバー側の一時的な制限。利用上限ではない	少し待つ
`API Error: Request rejected (429)`	APIキーなどに設定されたレート制限	認証情報を確認する

429エラー（Request rejected）の原因

Request rejected (429)は、公式ドキュメントによると、APIキー・Amazon Bedrock・Google Cloudのプロジェクトに設定されたレート制限に達したという意味です。

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

PlanのサブスクリプションでClaude Codeを使っている場合、本来ここには当たりません。それでも出たときに疑うのが、環境に残っているAPIキーです。

対処として、公式ドキュメントは次のように案内しています。「/status を実行して、アクティブな認証情報が予想されるものであることを確認します。環境内の迷走した ANTHROPIC_API_KEY は、サブスクリプションの代わりに低層キーを通じてリクエストを…」ルーティングできる、という内容です。

つまり、過去に設定したAPIキーの環境変数が残っていて、サブスクリプションではなくAPIキー経由で動いている可能性があります。

/status

/statusにAPI keyという行が出ていたら、それが使われています。サブスクリプションで使いたい場合は、そのシェルでANTHROPIC_API_KEYの設定を解除して、claudeを起動し直します。

同じ理由で出るのがCredit balance is too low（クレジット残高が低すぎます）です。サブスクリプションなのにこれが出たら、同じくAPIキーが先に使われていないかを/statusで確認します。

Server is temporarily limiting requests (not your usage limit)は、エラー文の括弧に書いてあるとおり、自分の使用量とは無関係のサーバー側の一時的な制限です。少し待って再送すれば通ります。続くときはステータスページを見ます。

session limit・weekly limit で使えないとき

利用上限に当たると、次のいずれかのエラー文が表示されます。

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

resetsの後ろが、使えるようになる時刻です。Claude Codeは、その時刻までリクエストをブロックします。

覚えておきたいのは、次の違いです。

上限の種類	モデルを切り替えれば使える？
session limit・weekly limit	使えない（すべてのモデルで共有されるため）
Opus limit・Sonnet limit	使える（別のモデルファミリーなら）

Opus limitに当たったら、/modelでSonnetに切り替えて続けられます。ただし公式ドキュメントによると、モデルごとにプロンプトキャッシュを持つため、切り替えた後の最初のリクエストは、会話全体を読み直します。

対処法は、公式ドキュメントに次のとおり載っています。

表示されたリセット時刻まで待つ
/usageで、プランの上限とリセット時刻を確認する
/usage-creditsで、追加の使用量（使用クレジット）を購入する（ProとMaxの場合）
プランをアップグレードして、上限そのものを上げる

さらに、待っている間の便利な動きもあります。claude.aiのサブスクリプションでサインインしていると、Claude Codeは開いたセッションのまま待機して、リセット直後に中断したタスクを自動で続きから再開できます。

待機中は、画面の下にUsage limit reached · continuing automatically at 3:45pm · esc to cancelと出ます。取り消したいときは、空のプロンプトでEscを押します。

上限に近づくと、You've used 85% of your session limit · resets 3:45pmのように、使用率の警告も出ます。

ハック（Hack）

僕の場合、上限に当たったときは、作業内容で3つに分けています。
1.急ぎの作業なら、使用クレジット（従量課金）を使って続ける。
2.Claude Codeでなくても進められる作業なら、Codexに切り替える。
3.区切りがつく場面なら、上限のタイミングでキリよく休憩。
などです。

上限そのものの仕組みと、待ち時間を減らす具体策は、以下の記事で詳しくまとめています。

/usageは今の残りを見るコマンド、ccusageは過去の使用量を数字で振り返る道具です。上限に当たる原因を探すなら、ccusageで消費が多かった日を見つけると分かりやすくなります。

Prompt is too long（コンテキスト上限）のエラー

もう一つ、「使えない」と感じやすいのが、会話が長くなりすぎたときのエラーです。

Prompt is too long

対話画面では、次のように表示されます。

Context limit reached · /compact or /clear to continue

これは利用上限ではなく、1回の会話に載せられる量（コンテキストウィンドウ）を超えたという意味です。会話や貼り付けたファイルが、モデルの記憶できる量に収まらなくなっています。

対処は、公式ドキュメントに従うと次のとおりです。

/compactで以前のやり取りを要約して、空きを作る
新しく始めるなら/clearで会話をリセットする
/contextで、何が容量を使っているのか内訳を確認する
使っていないMCPサーバーは/mcp disable <名前>で無効にする

/compact

/compactがNot enough messages to compact.と返すことがあります。これは、やり取りが1往復しかなく、要約する以前の会話がないという意味です。大きなファイルを一度に貼ったときに起こりやすいので、その場合は/clearをして、貼る量を減らします。

Error during compaction: Conversation too longと出たら、/compact自体が失敗しています。Escを2回押して数ターン前に戻り、もう一度/compactを実行します。戻っても足りなければ/clearを実行します。前の会話は/resumeで開き直せます。

/compactの使い方と、自動で圧縮される仕組みは、Claude Codeの/compactコマンドの使い方にまとめています。

Claude Codeのログインエラー・認証エラー（401・403）

ログインや認証のエラーは、自分の環境の問題なので、自分で直せます。基本の動きは「/statusで状態を見る → /loginでログインし直す」の2手です。

代表的なエラー文は、次の3つです。

エラー文	意味
`Not logged in · Please run /login`	このセッションで使える認証情報がない
`Login expired · Please run /login`	保存していたログインの更新に失敗して、認証情報が消えた
`Please run /login · API Error: 401 Invalid authentication credentials`	認証情報の形式は認識されたが、その背後のアカウントや組織が拒否された

API Error: 401（Not logged in）

Not logged in · Please run /loginが出たら、対処は次のとおりです。

/login

/loginを実行して、Claudeのサブスクリプション（またはConsoleアカウント）で認証し直します。

API Error: 401 Invalid authentication credentialsが出たときは、公式ドキュメントに順番が書いてあります。

まず/statusを打つ
/statusにAPI keyの行があれば、環境変数のANTHROPIC_API_KEYが優先されているので、/loginでは置き換わらない。APIキーを更新するか、unset ANTHROPIC_API_KEYを実行して、サブスクリプションに戻す（PowerShellならRemove-Item Env:ANTHROPIC_API_KEY）
/statusがログインだけを表示するなら、/loginを1回実行する
同じアカウントで同じメッセージが続くなら、アカウントか組織がアクティブでなくなっている。/statusで表示されるアカウントと組織を確認して、組織の管理者に相談する

「ログインし直しても直らない」ときの犯人は、環境に残ったAPIキーであることが多いので、/statusのAPI keyの行を先に見るのが近道です。

ログインを何度も求められる場合は、システムの時計のズレやmacOSの認証情報の保存まわりが原因のこともあります。詳しくは公式のインストールとログインのトラブルシューティングにまとまっています。

403エラーが出るとき

公式ドキュメントでは、OAuth errorや403 Forbiddenが出たときは、インストールとログインのトラブルシューティングの「ログインと認証」の項目を見るよう案内されています。

このほか、認証まわりで見かけやすい文言が次の2つです。

App unavailable in region：Claude Codeがその国では提供されていない。サポート対象国はAnthropicのページで確認できます
Claude Code access has not been granted for this account：そのアカウントにClaude Codeを使える権限が付いていない。組織のアカウントでは、管理者がClaude Codeを含むロールを付ける必要があります

インストール用のコマンドで403が返る場合は、ネットワークやプロキシが通信を止めていることがあります。VPNを切る、別のネットワークで試すなどで確かめます。

Claude Codeの接続エラー・ネットワークエラー

Unable to connect to APIは、Claude CodeからAnthropicのサーバーまで、通信が届いていないというエラーです。原因は、インターネット接続・VPN・プロキシ・ファイアウォールなど、自分の環境側にあります。

公式ドキュメントに載っているエラー文の例は次のとおりです。括弧内のコードが原因の手がかりです。

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

まず試すのは、同じターミナルからcurlでAnthropicのサーバーに届くかの確認です。

curl -I https://api.anthropic.com

Windows PowerShellでは、curlが別の機能の名前になっているため、curl.exe -I https://api.anthropic.comと打ちます。

結果の見方は次のとおりです。

`curl`の結果	意味	次にやること
応答が返ってこない・エラー	ネットワーク自体が届いていない	インターネット接続、VPN、会社のプロキシ、ファイアウォールを確認する
応答が返る	ネットワークは正常	環境変数などの設定の残りを疑う

curlは成功するのにClaude Codeだけが失敗するときは、ANTHROPIC_BASE_URLという環境変数が残っていることがよくあります。

これは、Claude Codeの接続先をapi.anthropic.com以外に変更する設定です。すでに動いていない中継サーバーのアドレスが残っていると、Connection refusedになります。次のコマンドで確認できます。

echo $ANTHROPIC_BASE_URL

何か表示されたら、シェルの設定ファイルから削除して、新しいターミナルでclaudeを起動し直します。

会社のプロキシを通している場合は、claudeを起動する前にHTTPS_PROXYを設定します。

SSL証明書のエラー

会社のネットワークなどで通信が中継・検査されていると、次のようなエラーになります。

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)

対処は、組織の証明書ファイルをNODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pemで指定することです。

NODE_TLS_REJECT_UNAUTHORIZED=0は設定しないでください。証明書の検証を完全に無効にしてしまうので、公式ドキュメントも明確に禁止しています。

家庭のネットワークでは、この種類のエラーはほとんど見かけません。

API Error: 400 が出るとき

400番台のエラーは、リクエストの内容そのものに問題がある場合に出ます。公式ドキュメントの「リクエストエラー」の項目に、内容ごとの文言と対処がまとまっています。

個人で当たりやすいのは、次の2つです。

会話が長すぎる：Prompt is too long。前の章の/compactと/clearで直ります
モデル名の指定が違う：There's an issue with the selected model。/modelで、アカウントで使えるモデルを選び直します

モデルの指定では、claude-sonnet-5のような細かいバージョン名ではなく、sonnetやopusといったエイリアス（短い呼び名）を使うと、古くなりにくくなります。

それでも直らない、見慣れないメッセージが出る、というときは、エラー文をそのままClaude Codeに貼って聞くか、/feedbackで報告します。

Claude Codeのインストールエラー（Windows・権限）

インストールで出るエラーは種類が多いので、この章では個人の方が当たりやすいものだけに絞ります。インストール手順そのものは、Claude Codeのインストール方法｜Mac・Windowsで始める手順で解説しています。

最も多いのが、インストールは成功したのに、claudeと打つと次のように言われるケースです。

環境	エラー文
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows（CMD）	`'claude' is not recognized as an internal or external command`

公式ドキュメントによると、これはインストール先のフォルダがシェルの検索パス（PATH）にないという意味です。macOSとLinuxでは~/.local/bin/claude、Windowsでは%USERPROFILE%\.local\bin\claude.exeに、claudeが置かれます。

💡 補足解説：PATH（パス）とは

PATHとは、ターミナルがコマンドを探しに行くフォルダの一覧です。claudeが置かれたフォルダがこの一覧に入っていないと、ファイルは存在するのに「見つからない」と言われます。

macOS（Zshが標準）の直し方は、次の2行です。

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

Windows PowerShellでは、次の2行でユーザーのPATHに追加します。追加したらターミナルを開き直します。

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User') [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

直ったかどうかは、次のコマンドでバージョンが出れば確認できます。

claude --version

Windowsでは、ほかにも次のようなコマンドの取り違えが起きます。

エラー文	原因	直し方
`'irm' is not recognized`	PowerShellではなくCMDで打っている	PowerShellを開いて`irm https://claude.ai/install.ps1 \	iex`を実行
`A parameter cannot be found that matches parameter name 'fsSL'`	macOS/Linux用の`curl … \	bash`をPowerShellで打っている	PowerShell用の`irm`コマンドを使う
`The token '&&' is not a valid statement separator`	PowerShellでCMD用のコマンドを打っている	PowerShell用の`irm`コマンドを使う

OSとシェルに合ったインストールコマンドを選ぶのが原因の大半です。公式のセットアップページで、自分の環境のコマンドをコピーし直すのが確実です。

そのほか、次のエラーも公式ドキュメントに対処があります。

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell：Git for WindowsかPowerShellのどちらも見つからない。Git for Windowsをインストールする（セットアップ中の「Add to PATH」を選ぶ）と直ります
running scripts is disabled on this system：npm経由でインストールしたときに、PowerShellの実行ポリシーが起動用のスクリプトを止めている。PowerShellインストーラーを使うと避けられます
Cask 'claude-code' is unavailable（Homebrew）：brew updateをしてからbrew install --cask claude-codeをやり直す

権限のエラー（EACCESなど）が出たときは、インストーラーが~/.local/bin/と~/.claude/に書き込めるかを確認します。

test -w ~/.local/bin && echo "writable" || echo "not writable"

not writableと出たら、公式ドキュメントの手順に従って、次の2行で自分を所有者にします。

sudo mkdir -p ~/.local/bin sudo chown -R $(whoami) ~/.local

VS Code・MCPのエラー

この章では、ほかの環境の組み合わせで起きやすいエラーを、2つに分けて紹介します。

VS Codeで出るエラー

VS Code（コードを書くエディタ）で使うClaude Codeで、次のエラーに当たる人が多いです。

拡張機能でClaudeが検出されない・接続されない
ターミナルでclaudeと打つとcommand not foundになる

2番目については、公式ドキュメントに大事な注意書きがあります。VS Code拡張機能は、claudeをPATHに追加しません。拡張機能は自分専用のコピーを拡張機能フォルダの中に持っているだけなので、拡張機能だけをインストールした場合、~/.local/bin/claudeは存在しません。

ターミナルからclaudeを使いたい場合は、別にスタンドアロン（単体）のインストールが必要です。

また、VS CodeでClaude Code process exited with code 1と出る場合は、公式のエラーリファレンスに個別の説明があります。

VS Code拡張機能とターミナルの違いや、つまずきやすい点は、Claude CodeをVS Codeで使う方法｜拡張機能とターミナルの違いで詳しく解説しています。

MCPの接続エラー

ハック（Hack）

僕が実際に何度か当たったのが、MCPの接続エラーです。外部ツールをつなぐ設定を追加した直後に、繋がらないと言われて、ツールが一覧に出てこない状態になりました。

MCP（外部のツールやデータベースとClaude Codeをつなぐ仕組み）の接続に失敗したときは、まず/mcpを打ちます。

/mcp

/mcpは、登録したMCPサーバーごとの接続状態を表示します。どのサーバーが繋がっていないのか、再認証が必要なのかが、ここで分かります。

それでも原因が分からないときは、僕は次の順で調べています。

/mcpで、どのサーバーが失敗しているかを確認する
失敗したサーバーの名前とエラー文を、そのままClaude Codeに貼って聞く
claude --safe-modeで起動して、MCPを無効にした状態で動くか確かめる
設定ファイル側の書き間違い（場所・ファイル名）を見直す

claude --safe-modeで動くなら、原因はプラグインやMCP、フックなどの追加設定側だと絞り込めます。

使っていないMCPサーバーが多いと、会話の容量を圧迫してPrompt is too longの原因にもなります。使わないものは/mcp disable <名前>で無効にしておきます。

MCPの設定ファイルの場所や接続のしかたは、以下の記事でまとめています。

Claude Codeでアプリを作る手順は、以下の記事にまとめています。

FAQ：Claude Codeのエラーでよくある質問

Claude Codeで500や529が出るのは、自分のせいですか？

自分のせいではありません。公式ドキュメントによると、5xx（500など）は「お客様のプロンプト、設定、またはアカウントが原因ではありません」とされています。529も、利用上限にはカウントされません。

エラーが出たら、まず何をすればいいですか？

エラー文を見て、次の順番で判断します。

5から始まる番号（500・529）→ status.claude.comを見て、少し待つ
hit your ... limit → /usageでリセット時刻を確認して、待つか切り替える
Not logged inや401 → /statusのあと、/login
Unable to connect → curl -I https://api.anthropic.comで確認
原因が分からない → /doctor

エラーが出ると、会話や作業は消えますか？

固まって再起動した場合も、会話は消えません。同じフォルダでclaude --resumeを実行すると、前の続きから再開できます。

Claude Codeを再インストールすれば直りますか？

再インストールが必要なのは、command not foundや、複数のインストールが混在している場合など、インストール自体の問題のときだけです。500・529・上限・ログインのエラーは、再インストールしても直りません。

インストールが混在しているかは、which -a claude（Windowsではwhere.exe claude）で確認できます。複数見つかったら、1つだけ残します。

エラーを予防する方法はありますか？

完全には防げませんが、次の3つでエラーの種類ごとに減らせます。

会話が長くなったら、早めに/compactをかける（Prompt is too longの予防）
使っていないMCPサーバーは無効にしておく（容量の節約）
使用量を/usageやccusageで定期的に確認し、上限の手前で作業の区切りをつける

設定まわりの整え方は、Claude Codeの初期設定ガイド｜settings.jsonの場所と権限の書き方にまとめています。

自分では直せないエラーは、どこに相談すればいいですか？

公式ドキュメントでは、次の順で案内されています。

/doctorで設定を確認し、/mcpでMCPの状態を確認する
Claude Code内の/feedbackでAnthropicに報告する
GitHubのリポジトリで、既知の問題を探す
Claude Codeに、機能について直接質問する（ドキュメントを参照できます）

アカウントや請求のトラブルは、Anthropicのサポートに連絡します。

まとめ：Claude Codeのエラーは、3つに分けて動く

5から始まる番号（500・529）はAnthropic側の問題。status.claude.comを見て待つか、/modelで別のモデルに切り替える
hit your ... limitは自分の利用上限。リセット時刻まで待つか、/usage-creditsでの追加購入や別ツールへの切り替えを選ぶ
Not logged in・401・Unable to connect・command not foundは自分の環境の問題。/status・/login・curl・PATHで自分で直せる
原因が分からないときは/doctor。エラー文は要約せず、そのままClaude Codeに貼って聞く