Claude Codeを使っていると、インストール時やログイン時、実際にコードを書かせている最中など、様々な場面でエラーに遭遇することがあります。この記事では、公式ドキュメントの情報をもとに、特によく報告されているエラーメッセージとその対処法を原因別に整理しました。

表示されたエラーメッセージの一部をこのページ内で検索(Ctrl+F / Cmd+F)すると、該当箇所にすぐジャンプできます。

目次 [ close ]
  1. 1. インストール時のエラー
    1. command not found: claude / 'claude' is not recognized
    2. インストールスクリプトがHTMLを返す(syntax error near unexpected token '<')
    3. Windowsでインストールコマンドを間違えている
    4. TLS/SSL証明書エラー(unable to get local issuer certificate など)
    5. 低メモリ環境でインストールがKilledされる
  2. 2. ログイン・認証エラー
    1. Not logged in · Please run /login
    2. OAuth error: Invalid code. Please make sure the full code was copied
    3. API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}
    4. This organization has been disabled(サブスクリプションは有効なのに出る場合)
    5. WSL2・SSH・コンテナ環境でOAuthログインが失敗する
  3. 3. API利用時のエラー(レート制限・利用上限)
    1. API Error: Repeated 529 Overloaded errors
    2. You've hit your session limit / You've hit your weekly limit
    3. Request rejected (429)
    4. Invalid API key · Fix external API key
    5. Credit balance is too low
  4. 4. 通信・ネットワークエラー
    1. Unable to connect to API / fetch failed
    2. SSL certificate verification failed / Self-signed certificate detected
  5. 5. コンテキスト・プロンプト関連のエラー
    1. Prompt is too long
    2. Error during compaction: Conversation too long
    3. Autocompact is thrashing: the context refilled to the limit...
  6. 6. パフォーマンス・フリーズの問題
    1. CPU・メモリ使用率が高い
    2. コマンドがフリーズ・無応答になる
  7. 7. それでも解決しない場合
  8. よくある質問(FAQ)
  9. まとめ

1. インストール時のエラー

command not found: claude / 'claude' is not recognized

インストール自体は成功しているものの、claudeコマンドにパス(PATH)が通っていないことが原因です。インストーラーはclaudeを以下の場所に配置します。

  • macOS/Linux: ~/.local/bin/claude
  • Windows: %USERPROFILE%\.local\bin\claude.exe

対処法 このディレクトリがPATHに含まれているか確認し、含まれていなければシェルの設定ファイル(~/.zshrcや~/.bashrcなど)に追加します。Windowsの場合はPowerShellで以下を実行してユーザーPATHに追加できます。

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

設定後はターミナルを再起動し、claude --versionで確認してください。

インストールスクリプトがHTMLを返す(syntax error near unexpected token '<')

curl -fsSL https://claude.ai/install.sh | bashのようなコマンドを実行した際に、シェルスクリプトの代わりにHTMLページが返ってきてしまうケースです。curl: (22) The requested URL returned error: 403と表示されることもあります。

主な原因は、利用している国・地域がClaude Codeの対応地域外であるか、ネットワークやプロキシがダウンロードをブロックしていることです。

対処法

  • 対応地域内であれば、数分待って再実行する
  • macOSならHomebrew(brew install --cask claude-code)、WindowsならWinGet(winget install Anthropic.ClaudeCode)など、別のインストール方法を試す

Windowsでインストールコマンドを間違えている

'irm' is not recognized、The token '&&' is not valid、A parameter cannot be found that matches parameter name 'fsSL'などのエラーは、シェルとインストールコマンドの組み合わせを間違えていることが原因です。

  • PowerShellでは: irm https://claude.ai/install.ps1 | iex
  • コマンドプロンプト(CMD)では: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

macOS/Linux用のcurl ... | bashコマンドをPowerShellでそのまま実行すると失敗するので、必ずシェルに合ったコマンドを使う必要があります。

TLS/SSL証明書エラー(unable to get local issuer certificate など)

TLS connect errorやSSL/TLS secure channel関連のエラーは、社内プロキシやセキュリティソフトがTLS通信を検査(インターセプト)していることが主な原因です。

対処法

  • Ubuntu/Debianの場合はsudo apt-get install ca-certificatesでCA証明書を更新する
  • Windowsの場合、PowerShellで[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12を実行してからインストーラーを再実行する
  • 社内プロキシが原因の場合、証明書ファイルを取得して--cacertオプションやNODE_EXTRA_CA_CERTS環境変数で指定する

低メモリ環境でインストールがKilledされる

小規模なVPSなど空きメモリが少ないLinux環境で、OOM Killer(メモリ不足時にプロセスを強制終了する仕組み)によってインストールが中断されるケースです。インストールにはおよそ512MBの空きメモリが必要です。

対処法 スワップ領域を追加することで解決できます。

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

2. ログイン・認証エラー

Not logged in · Please run /login

有効な認証情報がないセッションで表示されます。/loginを実行してAnthropicアカウントでサインインすれば解決します。ログイン画面が何度も表示される場合は、システムの時計がずれていないか確認してください(トークンの検証には正確な時刻が必要です)。

OAuth error: Invalid code. Please make sure the full code was copied

ログインコードの有効期限が切れたか、コピー時に一部が欠けてしまった場合に表示されます。ブラウザが自動で開かない場合は、ターミナル上でcキーを押すとログイン用URLをクリップボードにコピーできます。

API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}

ログイン後にこのエラーが出る場合、以下を確認してください。

  • Claude Pro/Maxユーザー: サブスクリプションが有効かclaude.ai/settingsで確認する
  • Anthropic Consoleユーザー: アカウントに「Claude Code」または「Developer」ロールが割り当てられているか確認する
  • 社内プロキシ配下の場合: プロキシがAPIリクエストに干渉している可能性がある

This organization has been disabled(サブスクリプションは有効なのに出る場合)

有効なサブスクリプションがあるにもかかわらずこのエラーが出る場合、古いANTHROPIC_API_KEY環境変数がシェルに残っていて、それがサブスクリプションのログイン情報より優先されてしまっていることが原因です。以前の職場やプロジェクトで設定したAPIキーが.zshrcや.bashrcに残っているケースがよくあります。

対処法

unset ANTHROPIC_API_KEY
claude

~/.zshrcや~/.bashrc、Windowsならユーザー環境変数からANTHROPIC_API_KEYを探して削除すると恒久的に直ります。/statusコマンドで現在使われている認証方法を確認できます。

WSL2・SSH・コンテナ環境でOAuthログインが失敗する

ブラウザが別のホストで開いてしまい、ローカルのコールバックサーバーにリダイレクトが届かないことが原因です。サインイン後にブラウザ側にログインコードが表示されるので、それをターミナルに貼り付ければログインが完了します。

WSL2でブラウザ自体が開かない場合は、BROWSER環境変数にWindows側のブラウザパスを設定します。

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

3. API利用時のエラー(レート制限・利用上限)

API Error: Repeated 529 Overloaded errors

Anthropic側のAPIが一時的に全ユーザーに対して高負荷状態になっていることを示します。自分の利用上限(クオータ)とは無関係です。

対処法

  • status.claude.comで障害情報を確認する
  • 数分待って再試行する
  • /modelで別のモデルに切り替える(モデルごとに負荷状況が異なるため)

You've hit your session limit / You've hit your weekly limit

契約しているプランの利用可能枠を使い切った状態です。メッセージに表示されているリセット時刻まで待つ必要があります。

対処法

  • /usageで現在のプラン上限とリセット時刻を確認する
  • 追加利用枠が必要な場合は/usage-creditsで購入する(Pro/Maxプラン)
  • 恒常的に上限に達してしまう場合は、上位プランへのアップグレードも検討する

Request rejected (429)

APIキーやプロジェクトに設定されたレート制限に達した状態です。

対処法

  • /statusで現在使われている認証情報が意図したものか確認する(意図しないAPIキーが設定されていると、サブスクリプションではなく低ティアのキー経由でリクエストされてしまうことがある)
  • 同時並行で動かしているサブエージェントの数を減らす、またはCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY環境変数で同時実行数を下げる

Invalid API key · Fix external API key

ANTHROPIC_API_KEY環境変数、またはapiKeyHelperスクリプトが返したキーがAPI側に拒否された状態です。

対処法

  • キーにタイプミスがないか、Consoleで無効化(revoke)されていないか確認する
  • env | grep ANTHROPICを実行し、意図しない古いキーが読み込まれていないか確認する(.envファイルなどから自動で読み込まれることがある)
  • サブスクリプション認証を使いたい場合はANTHROPIC_API_KEYをunsetしてから/loginする

Credit balance is too low

Consoleで従量課金(APIキー)を使っている場合に、プリペイドクレジットが枯渇した状態です。platform.claude.com/settings/billingでクレジットを追加するか、Pro/Max/Team/Enterpriseプランがあれば/loginでサブスクリプション認証に切り替えます。

4. 通信・ネットワークエラー

Unable to connect to API / fetch failed

APIサーバーへのTCP接続自体が失敗している状態です。インターネット接続がない、VPNがapi.anthropic.comをブロックしている、社内プロキシが必要なのに未設定、などが主な原因です。

対処法

  • curl -I https://api.anthropic.com(Windows PowerShellではcurl.exe -I)で接続確認する
  • 社内プロキシ配下の場合はHTTPS_PROXY環境変数を設定してから起動する
  • ファイアウォールが必要な通信先をブロックしていないか確認する

SSL certificate verification failed / Self-signed certificate detected

社内ネットワークのプロキシやセキュリティ製品がTLS通信を独自証明書でインターセプトしており、Claude Codeがその証明書を信頼できていない状態です。

対処法 組織のCA証明書バンドルを取得し、NODE_EXTRA_CA_CERTS環境変数でそのパスを指定します。

export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem

NODE_TLS_REJECT_UNAUTHORIZED=0で証明書検証自体を無効化するのは、通信の安全性が失われるため避けてください。

5. コンテキスト・プロンプト関連のエラー

Prompt is too long

会話の内容と添付ファイルの合計が、モデルのコンテキストウィンドウの上限を超えた状態です。

対処法

  • /compactで会話を要約してコンテキストを空ける、または/clearで新しい会話を始める
  • /contextで何がコンテキストを圧迫しているか(システムプロンプト、ツール定義、メモリファイル、メッセージなど)を確認する
  • 使っていないMCPサーバーを/mcp disable <name>で無効化し、ツール定義の分だけコンテキストを削減する
  • CLAUDE.mdが肥大化している場合はスリム化する

Error during compaction: Conversation too long

/compactを実行しようとしても、要約結果を格納する空きコンテキストが足りずに失敗する状態です。

対処法 Escキーを2回押してメッセージ一覧を開き、直近の数メッセージ分を巻き戻してから再度/compactを実行します。それでも解決しない場合は/clearで新しいセッションを開始してください(以前の会話は/resumeで復元可能です)。

Autocompact is thrashing: the context refilled to the limit...

自動要約(auto-compact)は成功しているのに、直後にファイルやツールの出力が再びコンテキストを埋め尽くしてしまい、同じ処理をループしている状態です。

対処法

  • 巨大なファイルはClaudeに全体ではなく特定の行範囲・関数単位で読み込ませる
  • /compact keep only the plan and the diffのように、対象を絞って/compactを実行する
  • 大きなファイルを扱う処理はサブエージェントに任せ、別のコンテキストウィンドウで実行させる

6. パフォーマンス・フリーズの問題

CPU・メモリ使用率が高い

大規模なコードベースを処理する際に、リソース消費が大きくなることがあります。

対処法

  • /compactをこまめに実行してコンテキストサイズを抑える
  • 大きなタスクの区切りでClaude Codeを再起動する
  • node_modulesやビルド成果物のディレクトリを.gitignoreに追加する
  • claude --safe-modeで起動し、プラグイン・MCPサーバー・フックのどれが原因かを切り分ける

コマンドがフリーズ・無応答になる

Ctrl+Cで現在の処理のキャンセルを試み、それでも反応がなければターミナルを閉じて再起動します。会話は失われないため、同じディレクトリでclaude --resumeを実行すればセッションを再開できます。

7. それでも解決しない場合

上記で解決しない場合は、以下を順番に試してください。

  1. Claude Code内で/doctorを実行し、セットアップ全体の自動診断を行う(claude自体が起動しない場合はターミナルからclaude doctorを実行)
  2. /mcpでMCPサーバーの接続状況を確認する
  3. GitHubリポジトリで同様の問題が報告されていないか検索する
  4. Claude Code内で/feedbackを実行し、Anthropicに直接問題を報告する

よくある質問(FAQ)

Q. エラーメッセージの意味を調べる一番早い方法は？ A. Claude Code内で/doctorを実行すると、インストール状況・設定・拡張機能・コンテキスト使用量などを自動でチェックし、修正案を提示してくれます。

Q. command not foundと出て動きません。再インストールが必要ですか？ A. 多くの場合、再インストールではなくPATHの設定漏れが原因です。インストール自体はやり直さず、シェルの設定ファイルにインストールディレクトリを追加してください。

Q. 429や529エラーは自分のプランの上限に達したということですか？ A. いいえ。429はAPIキーやプロジェクトに設定されたレート制限、529はAnthropic側のAPI全体の混雑状況によるもので、どちらも「セッション利用上限に達した」という通知(You've hit your session limitなど)とは別物です。

まとめ

Claude Codeのエラーは、大きく分けると「インストール・PATH」「ログイン・認証」「API利用制限」「ネットワーク」「コンテキスト超過」「パフォーマンス」の6種類に整理できます。エラーメッセージの一部をそのままこの記事内で検索すれば、該当する原因と対処法にすぐたどり着けるはずです。

まずは/doctorを実行してみるのが、どのエラーに対しても最初の一歩としておすすめです。