Claude Codeのインストールでcommand not foundが出るときの対処法は？

インストール先ディレクトリ（~/.local/bin）がシェルのPATHに含まれていないことが原因です。macOSなら~/.zshrcに、Linuxなら~/.bashrcに export PATH="$HOME/.local/bin:$PATH" を追加し、source コマンドで反映させてください。ネイティブインストーラーを使えばPATH設定は自動で行われます。

Claude Codeのレート制限（Rate limit reached）を回避する方法は？

3種類の制限があります。セッション/週間制限はリセット時刻まで待機するか、/model sonnet で軽量モデルに切り替えてください。API制限（429）は数秒待てば自動リセットされます。/cost で使用量を確認し、/extra-usage で追加枠の購入も可能です。

Claude CodeのMCPサーバーに接続できないときはどうすればいい？

.mcp.json設定でコマンドのフルパス指定、サーバー名の制約（英数字・ハイフン・アンダースコアのみ、64文字以内）、環境変数の明示的設定を確認してください。/doctor でMCPサーバーの接続状態を一括診断できます。

Claude Codeが急に遅くなった原因は何？

主な原因は3つあります。(1) コンテキストの肥大化 → /compact で圧縮 (2) プラグインやMCPサーバーの競合 → 不要なサーバーを /mcp disable で無効化 (3) メモリリーク → Claude Codeを再起動。/context でコンテキスト使用状況を確認するのが最初のステップです。

Claude CodeはProプランで使えなくなったのか？

2026年5月時点では、Proプラン（月額20ドル）でClaude Codeを利用可能です。過去に一部ユーザーで利用制限が報告されたケースがありましたが、/status で現在の認証状態とプランを確認してください。最新のプラン情報は claude.ai/pricing で確認できます。

Claude Codeのコンテキスト上限に達したらどうする？

/compact で会話履歴を要約して圧縮するのが最も手軽です。特定の情報だけ残したい場合は /compact keep only the plan and the diff のように指示できます。完全にリセットする場合は /clear を実行してください。大きなファイルの処理はサブエージェントに委任すると、別のコンテキストウィンドウで実行されます。

Claude Code for VS Codeが応答なしになる場合の対処法は？

コマンドパレット（Cmd+Shift+P）から「Claude Code: Restart」を実行してください。改善しない場合は拡張機能の無効化→再有効化、またはバージョンのダウングレードを試してください。VS Code自体とClaude Code拡張機能を最新に保つことが予防策です。

Claude Codeの障害情報はどこで確認できる？

status.claude.com でAnthropicのサービス稼働状況をリアルタイムで確認できます。Claude Code内から /feedback でバグ報告も可能です。既知の問題はGitHub（github.com/anthropics/claude-code）のIssuesで検索・報告できます。

development·2026-05-02

Claude Codeのエラー対処法｜トラブルシューティング完全ガイド【2026年最新】

Claude Codeで発生するエラーの原因と解決法を網羅的に解説。インストール・認証・レート制限・MCP接続・コンテキスト超過・IDE統合まで、実際のエラーメッセージと解決手順を体系的にまとめたトラブルシューティングガイドです。

#Claude Code #トラブルシューティング #エラー対処法

Claude Codeのエラー対処法｜トラブルシューティング完全ガイド【2026年最新】

Claude Codeを使っていると、command not foundで起動できない、429でレート制限に引っかかる、MCPサーバーに接続できない — こうしたエラーに遭遇する場面は少なくありません。ターミナル上で動作する特性上、環境依存のトラブルが起きやすいためです。

本記事では、実際に表示されるエラーメッセージごとに「原因」「解決手順」「予防策」を整理し、最短でエラーを解決できるトラブルシューティングガイドをお届けします。

この記事を読むとわかること

エラーを3分類（インストール系・実行時系・環境依存系）して素早く原因を特定する方法
/doctorの出力結果の読み方と、各項目の対処法
頻出エラー20種類以上の「エラーメッセージ → 原因 → 解決手順 → 予防策」の4点セット
MCP接続エラーの体系的なデバッグ手順
IDE統合（VS Code・JetBrains）固有のトラブル解決法

Claude Codeエラーの3分類と解決フローチャート

Claude Codeで発生するエラーは、大きく3つのカテゴリに分類できます。エラーに遭遇したら、まずどのカテゴリに該当するかを判断し、該当セクションに直接ジャンプしてください。

カテゴリ	典型的な症状	該当セクション
インストール・セットアップ系	`command not found`、`EACCES`、TLSエラー、インストール失敗	インストール・セットアップ系エラー
実行時系	`429`、`529`、`Prompt is too long`、MCP接続失敗、認証エラー	認証系 / レート制限系 / コンテキスト系 / MCP系
環境依存系	IDE応答なし、WSL検索が遅い、プロキシ接続不可	IDE統合 / ネットワーク・環境別

最短ルート: どのカテゴリかわからない場合は、次のセクションで紹介する/doctorコマンドを実行してください。インストール、設定、MCP、コンテキスト使用量を一括で診断できます。

まずやるべきこと — /doctorで一括自己診断

/doctorは、Claude Codeに内蔵された自己診断コマンドです。エラーの原因を手動で一つずつ確認する前に、まず/doctorを実行することで問題を素早く切り分けられます。

実行方法

Claude Codeが起動できる場合は、セッション内で以下を実行します。

/doctor

Claude Codeがまったく起動しない場合は、シェルから直接実行します。

claude doctor

/doctorが診断する項目

診断項目	チェック内容	問題がある場合の対処
インストール状態	バイナリの存在、PATHの設定、バージョン整合性	PATHの追加、再インストール
設定の有効性	settings.json、CLAUDE.mdの構文エラー	設定ファイルの修正
MCP サーバー	各MCPサーバーの接続状態、設定の整合性	.mcp.json設定の修正
コンテキスト使用量	コンテキストウィンドウの消費状況、大きなメモリファイル	`/compact`でコンテキスト圧縮
認証状態	OAuthトークン、APIキーの有効性	`/login`で再認証

/doctorの出力で具体的な問題が特定されたら、以下の各セクションで詳しい解決手順を確認してください。Claude Codeのスラッシュコマンド一覧では、/doctor以外の便利なコマンドも紹介しています。

インストール・セットアップ系エラーと解決法

Claude Codeのインストールで最も多いトラブルは、PATHの設定問題と権限エラーです。以下に頻出するエラーメッセージと対処法をまとめます。

command not found: claude

エラーメッセージ:

OS	表示されるメッセージ
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

原因: インストールは完了しているが、Claude Codeのバイナリが配置されるディレクトリ（~/.local/bin）がシェルのPATHに含まれていません。

解決手順:

macOS（Zsh）の場合:

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

Linux（Bash）の場合:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version

Windows PowerShellの場合:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
# ターミナルを再起動後に確認
claude --version

予防策: ネイティブインストーラー（curl -fsSL https://claude.ai/install.sh | bash）はPATHの設定を自動で行います。npmでグローバルインストールした場合にこの問題が起きやすいため、ネイティブインストーラーの利用を推奨します。

EACCES permission denied

エラーメッセージ: EACCES: permission denied

原因: ~/.local/bin/や~/.claude/ディレクトリへの書き込み権限がありません。

解決手順:

# ディレクトリの書き込み権限を確認
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

# 権限がない場合は修正
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

予防策: sudo npm install -g でのインストールは避けてください。ネイティブインストーラーを使えばこの問題は発生しません。

TLS/SSLエラー

エラーメッセージ: curl: (35) TLS connect error や unable to get local issuer certificate

原因: 企業のプロキシやファイアウォールがTLS通信をインターセプトしているケースが大半です。

解決手順:

# 1. CA証明書を更新（Ubuntu/Debian）
sudo apt-get update && sudo apt-get install ca-certificates

# 2. 企業プロキシ環境の場合、CA証明書を指定してインストール
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash

# 3. インストール後、Claude CodeのAPI通信にも同じ証明書を適用
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

予防策: 企業環境では、IT部門からCA証明書ファイルを入手し、NODE_EXTRA_CA_CERTS環境変数をシェルプロファイルに永続的に設定しておきましょう。企業環境でのClaude Code導入も参考にしてください。

インストールスクリプトがHTMLを返す

エラーメッセージ:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

原因: インストールURLがスクリプトではなくHTMLページを返しています。ネットワークの問題、地域制限、または一時的なサービス中断が考えられます。

解決手順:

# macOSの場合はHomebrewで代替インストール
brew install --cask claude-code

# Windowsの場合はWinGetで代替インストール
winget install Anthropic.ClaudeCode

# または数分後に再試行
curl -fsSL https://claude.ai/install.sh | bash

予防策: HTMLに「App unavailable in region」と表示される場合、お住まいの国ではClaude Codeが利用できません。Anthropicの対応国リストを確認してください。

低メモリLinuxサーバーでKilled

エラーメッセージ: インストール中にKilledが表示される

原因: Linux OOM Killerがメモリ不足のためプロセスを終了しました。Claude Codeには少なくとも4GBのRAMが必要です。

解決手順:

# スワップスペースを追加（2GB）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 再度インストール
curl -fsSL https://claude.ai/install.sh | bash

予防策: VPSやクラウドインスタンスでは、4GB以上のRAMを持つインスタンスを使用するか、事前にスワップスペースを設定してください。

認証・APIキー・プラン系エラーと解決法

認証エラーは、Claude Codeが APIサーバーに対して正しく身元を証明できないときに発生します。/statusコマンドで現在の認証方法を確認できます。

Invalid API Key

エラーメッセージ: Invalid API key · Fix external API key

原因: ANTHROPIC_API_KEY環境変数に設定されたキーが無効（タイプミス、取り消し済み、古い形式）です。

解決手順:

# 現在設定されているキーを確認
env | grep ANTHROPIC

# APIキーをアンセットしてサブスクリプション認証に切り替え
unset ANTHROPIC_API_KEY
claude

予防策: .envファイルやシェルプロファイルに古いAPIキーが残っていないか定期的に確認してください。特にdirenvやdotenvプラグインが自動で読み込むケースに注意が必要です。

403 Forbidden

エラーメッセージ: API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}

原因: サブスクリプションが無効、またはアカウントに適切なロールが割り当てられていません。

解決手順:

Pro/Maxユーザー: claude.ai/settingsでサブスクリプションがアクティブか確認
Consoleユーザー: アカウントに「Claude Code」または「Developer」ロールがあることを管理者に確認
プロキシ環境: 企業プロキシがAPIリクエストに干渉している可能性があるため、プロキシ設定を確認

This organization has been disabled

エラーメッセージ: API Error: 400 ... This organization has been disabled

原因: 無効化された組織に紐づく古いANTHROPIC_API_KEYが、サブスクリプション認証をオーバーライドしています。ANTHROPIC_API_KEY環境変数はOAuth認証より優先されるため、シェルプロファイルや.envファイルに残っている古いキーが原因です。

解決手順:

# 環境変数をアンセット
unset ANTHROPIC_API_KEY

# シェルプロファイルからも削除
# ~/.zshrc や ~/.bashrc で export ANTHROPIC_API_KEY=... の行を削除

# 再起動して確認
claude
/status

OAuthエラーとトークン期限切れ

エラーメッセージ: OAuth token revoked · Please run /login または OAuth token has expired · Please run /login

原因: 保存されたOAuthトークンが取り消されたか期限切れになっています。

解決手順:

/login

頻繁にログインを求められる場合は、システムクロックが正確かどうかを確認してください。macOSではKeychainのロックや同期問題も原因になります。

予防策: macOSでKeychainの問題が疑われる場合は、claude doctorを実行してKeychainアクセスを確認してください。

Claude Codeの料金プランとレート制限では、プラン別の機能差やアップグレードの判断基準も解説しています。

レート制限・使用量系エラーと解決法

レート制限エラーは、使用量がアカウントやプランの上限に達したときに発生します。重要なのは、3種類の制限が存在することを理解することです。

制限の種類	エラーメッセージ	リセット
セッション制限	`You've hit your session limit`	表示されたリセット時刻まで待機
週間制限	`You've hit your weekly limit`	ローリングウィンドウでリセット
API制限（RPM/TPM）	`Request rejected (429)`	数秒〜数分で自動リセット

セッション・週間制限（サブスクリプション）

エラーメッセージ: You've hit your session limit · resets 3:45pm または You've hit your weekly limit

原因: Pro/Maxプランのローリング使用許容量を使い切りました。

解決手順:

リセット時刻まで待機
/usageで現在の使用状況とリセット時刻を確認
/model sonnetや/model haikuで軽量モデルに切り替えて作業を継続
/extra-usageで追加使用量を購入（Pro/Maxプラン）

予防策: /costでセッション中の使用量を定期的に確認し、大きなタスク開始前に/statusで残量を把握してください。

529 Overloaded（サーバー過負荷）

エラーメッセージ: API Error: Repeated 529 Overloaded errors · check status.claude.com

原因: APIサーバー全体が一時的に容量に達しています。529はアカウントのクォータとは無関係です。

解決手順:

status.claude.com でインシデント情報を確認
数分待ってから再試行
/modelで別のモデルに切り替え（モデルごとに容量が管理されているため）

Credit balance is too low

エラーメッセージ: Credit balance is too low

原因: API Console組織のプリペイドクレジットが不足しています。

解決手順:

platform.claude.comでクレジットを追加
自動リロードを有効にして残高不足を防止
Pro/Maxプランがある場合は/loginでサブスクリプション認証に切り替え

予防策: API Console設定で自動リロード閾値を設定しておくと、作業中にクレジット切れで中断されることを防げます。

コンテキスト・メモリ系エラーと解決法

コンテキストエラーは、会話の蓄積やファイルの添付によりモデルのコンテキストウィンドウが限界に達したときに発生します。Claude Codeのコンテキスト・メモリ管理で詳しい管理手法を解説しています。

Prompt is too long

エラーメッセージ: Prompt is too long

原因: 会話履歴、システムプロンプト、ツール定義、添付ファイルの合計がモデルのコンテキストウィンドウを超えています。

解決手順:

# 1. コンテキストを要約して圧縮
/compact

# 2. 特定の情報だけ残して圧縮（推奨）
/compact keep only the plan and the diff

# 3. 完全にリセットして新しいセッションを開始
/clear

# 4. コンテキストの内訳を確認
/context

予防策:

自動コンパクトはデフォルトで有効です。DISABLE_AUTO_COMPACT環境変数を設定している場合は再度有効にしてください
使用していないMCPサーバーは/mcp disable <name>で無効化し、ツール定義によるコンテキスト消費を削減してください
大きなファイルはパスで参照し、内容を直接貼り付けないようにしましょう

自動コンパクションのスラッシングエラー

エラーメッセージ: Autocompact is thrashing: the context refilled to the limit...

原因: 自動コンパクションは成功したものの、大きなファイルやツール出力がコンテキストウィンドウを繰り返し満杯にしています。

解決手順:

大きなファイルは全体ではなく行範囲を指定して読むよう依頼する
/compact keep only the plan and the diffで焦点を絞って圧縮
大規模なファイル作業はサブエージェントに移動（別のコンテキストウィンドウで実行される）
/clearで新しいセッションを開始

Request too large

エラーメッセージ: Request too large (max 30 MB)

原因: コンテキストウィンドウの制限とは別に、HTTPリクエスト自体のバイトサイズ制限（30MB）を超えています。大きなファイルの貼り付けが原因です。

解決手順: Escキーを2回押して、サイズ超過の原因となったターンに戻ってください。大きなファイルは貼り付けではなくパスで参照し、Claudeにチャンク単位で読み取らせてください。

MCP接続エラーの体系的デバッグ

MCP（Model Context Protocol）は外部ツールとの連携を可能にする仕組みですが、設定ミスが起きやすい箇所でもあります。Claude Code MCP連携ガイドで基本的な設定方法を確認できます。

Could not connect to MCP server

エラーメッセージ: Could not connect to MCP server または Connection closed

原因: MCPサーバーの起動に失敗しているか、接続が確立できていません。

デバッグ手順:

ステップ1: .mcp.json設定の検証

# プロジェクトの.mcp.jsonを確認
cat .mcp.json

# ユーザー全体の設定を確認
cat ~/.claude/settings.json

確認ポイント:

コマンドのパスが正しいか（相対パスではなくフルパスを推奨）
サーバー名が英数字・アンダースコア・ハイフンのみで1〜64文字以内か
JSON構文にエラーがないか

ステップ2: コマンドの実行確認

# MCPサーバーのコマンドが直接実行できるか確認
which npx  # または which uvx
npx --version

Pythonベースのサーバーでuvxが見つからない場合:

# uvをインストール
pip install uv

ステップ3: 環境変数の継承問題

Claude CodeのMCPサーバーは、シェルの環境変数を自動的に継承しません。必要な環境変数は.mcp.json内で明示的に設定してください。

{
  "mcpServers": {
    "my-server": {
      "command": "/full/path/to/npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

ステップ4: Windows環境での注意

Windows環境では、npxを使用するMCPサーバーにcmd /cラッパーが必要な場合があります:

{
  "mcpServers": {
    "my-server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "my-mcp-server"]
    }
  }
}

予防策: MCPサーバーを追加する際は、claude mcp addコマンドを使うと設定ミスを減らせます。/doctorを実行すれば、MCPサーバーの接続状態を一括確認できます。

Claude Code Hooks自動化ガイドでは、設定のデバッグ方法についても解説しています。

パフォーマンス・安定性のトラブルと解決法

以下の問題はエラーメッセージが表示されないケースです。症状から対処法を確認してください。

応答が遅い・フリーズする

症状: Claude Codeが応答しない、または極端に遅い

原因と対処:

コンテキストの肥大化: /compactでコンテキストを圧縮
CPU/メモリ使用量: 主要なタスク間でClaude Codeを閉じて再起動
大規模ビルドディレクトリ: .gitignoreにビルドディレクトリを追加

フリーズした場合:

# 1. Ctrl+Cで現在の操作をキャンセル
# 2. 応答しない場合はターミナルを閉じて再起動
# 3. セッションを再開（会話は失われない）
claude --resume

メモリ使用量が改善しない場合は、/heapdumpコマンドでJavaScriptヒープスナップショットを生成し、Chrome DevToolsで分析できます。

「Claudeが雑になった」と感じたら

症状: エラーは出ないが、回答の品質が低下しているように感じる

Claude Codeがモデルバージョンを静かに変更することはありませんが、以下の要因で品質が低下して見えることがあります。

チェックリスト:

モデルを確認: /modelを実行し、意図したモデルが選択されているか確認。ANTHROPIC_MODEL環境変数や設定ファイルで小さなモデルが指定されている場合がある
effortレベルを確認: /effortを実行し、推論レベルを確認。高度なデバッグ作業にはhighやultrathinkを設定
コンテキスト圧力を確認: /contextでウィンドウの使用状況を確認。容量に近い場合は/compactを実行
巻き戻し: 品質の低い回答が出た場合、修正で返信するよりEscキーを2回押して巻き戻す方が効果的

検索がファイルを見つけられない

症状: SearchツールやFile参照でファイルが見つからない

原因: バンドルされたripgrepバイナリがシステムで実行できない可能性があります。

解決手順:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# その後、環境変数を設定
export USE_BUILTIN_RIPGREP=0

IDE統合のトラブルシューティング

VS Code拡張機能の応答なし問題

症状: Claude Code for VS Codeが更新アイコンが表示されたまま応答しない

解決手順:

VS Codeのコマンドパレット（Cmd+Shift+P / Ctrl+Shift+P）を開く
「Claude Code: Restart」を実行
改善しない場合は拡張機能を無効化→再有効化
それでも改善しない場合は拡張機能のバージョンをダウングレード

予防策: VS Code自体とClaude Code拡張機能を最新バージョンに保ってください。

JetBrainsプラグインの検出問題

症状: No available IDEs detectedエラーが表示される

原因: WSL2環境でのネットワーク設定またはWindowsファイアウォールによるブロックが原因の場合があります。

解決手順:

JetBrains IDEが起動していることを確認
ファイアウォール設定でJetBrains IDEの通信を許可
WSL2環境の場合はネットワーク設定を確認

Claude Codeの使い方完全ガイドでは、各種IDE連携の設定方法も解説しています。

ネットワーク・環境別トラブルシューティング

Unable to connect to API

エラーメッセージ: Unable to connect to API. Check your internet connection や ECONNREFUSED、ETIMEDOUT

原因: インターネット接続の問題、VPNによるブロック、または企業プロキシの設定不備です。

解決手順:

# APIサーバーへの接続を確認
curl -I https://api.anthropic.com

# 企業プロキシ環境の場合
export HTTPS_PROXY=http://proxy.example.com:8080
claude

予防策: 企業環境では、IT部門にClaude Codeがアクセスするホストのホワイトリスト登録を依頼してください。

SSL証明書エラー（企業環境）

エラーメッセージ: SSL certificate verification failed や Self-signed certificate detected

原因: 企業のプロキシやセキュリティアプライアンスがTLS通信をインターセプトしており、その証明書がNode.jsに信頼されていません。インストール時のTLS/SSLエラーについては「インストール・セットアップ系エラー」セクションのTLS/SSLエラーも参照してください。

解決手順:

# 企業のCA証明書をNode.jsに認識させる
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem

NODE_TLS_REJECT_UNAUTHORIZED=0は証明書検証を完全に無効にするため、絶対に設定しないでください。

Windows/WSL固有の問題

WSLでの検索パフォーマンス問題:

WSLからWindowsファイルシステム（/mnt/c/）を操作する場合、ファイルI/Oのパフォーマンスペナルティが発生し、検索結果が少なくなることがあります。

解決策:

プロジェクトをLinuxファイルシステム（/home/配下）に配置
検索時にディレクトリやファイルタイプを指定してスコープを絞る
ネイティブWindows版のClaude Codeの利用を検討

WSL1でのExec format error:

WSL1ではネイティブバイナリの互換性問題があります。WSL2への変換を推奨します:

wsl --set-version <DistroName> 2

トラブルシューティングのベストプラクティス

日常的なメンテナンス習慣を身につけることで、エラー発生を予防し、発生時にも素早く対処できます。

エラー発生時の基本フロー

/doctorを実行 — インストール、設定、MCP、認証を一括診断
エラーメッセージを確認 — 本記事の対応セクションで解決手順を確認
公式リソースを参照 — status.claude.comでサービス障害を確認

定期メンテナンス習慣

頻度	アクション	コマンド
セッション中	コンテキストが大きくなったら圧縮	`/compact`
セッション中	使用量を確認	`/cost`
タスク切り替え時	Claude Codeを再起動	ターミナル再起動
週1回	Claude Codeをアップデート	`claude update`
問題発生時	自己診断	`/doctor`

公式サポートリソース

リソース	用途	アクセス方法
サービス稼働状況	障害発生時の確認	status.claude.com
フィードバック送信	バグ報告・機能要望	`/feedback`
既知の問題	同じ問題の確認・報告	GitHub Issues
公式ドキュメント	最新の仕様確認	code.claude.com/docs