Claude Codeのエラー・トラブル解決ガイド｜症状別チェックリスト

Claude Codeが動かないときは、いきなり再インストールしたり権限を最大化したりせず、表示された症状を保存し、環境→認証→設定→対象処理の順に切り分けると原因を見つけやすくなります。

最初に次の情報をメモしてください。APIキー、トークン、顧客情報、社内パスなど秘密情報は貼り付けません。

- 発生時刻：
- OSとバージョン：
- ターミナル：
- Claude Codeのバージョン：
- 実行した操作：
- エラー文（秘密情報を除外）：
- 直前に変えた設定・ネットワーク・認証：
- 同じ操作を別フォルダで再現するか：

解説

本記事は安全な切り分け手順です。組織管理端末では、管理者ポリシーや社内サポートの手順を優先してください。

まず実行する共通確認

1. 公式の診断を実行

claude doctor

インストール方式、バージョン、設定などの診断結果を確認します。結果を共有するときは、ユーザー名、ローカルパス、組織情報、トークンなどをマスクしてください。

2. バージョンと実行場所を確認

claude --version
pwd

想定したプロジェクト内にいるか、古い実行ファイルを呼んでいないかを見ます。Mac・Linuxではwhich claude、Windowsではwhere.exe claudeで実行ファイルの候補を確認できます。

3. 小さな空フォルダで再現する

機密情報を含まない新しい作業フォルダで起動できるか確認します。

• 空フォルダでも失敗：インストール、認証、ネットワーク、端末設定の可能性
• 特定プロジェクトだけ失敗：プロジェクト設定、権限、Hooks、MCP、ファイル構成の可能性
• 特定操作だけ失敗：対象コマンド、OS権限、依存関係の可能性

「claude: command not found」または認識されない

主な原因

• インストールが完了していない
• 実行ファイルの場所がPATHに含まれていない
• インストール後にターミナルを開き直していない
• 複数のインストール方式が混在している
• WindowsでPowerShellとWSLの環境を混同している

安全な確認順

1. 使用した公式インストール手順とOSを確認
2. ターミナルを新しく開く
3. which claudeまたはwhere.exe claudeで候補を確認
4. claude --versionが返るか確認
5. 複数候補がある場合、削除する前にどれが使われているか記録

OS別の公式インストールと更新は、

を参照してください。Windowsネイティブ、PowerShell、WSLの切り分けは、

で説明しています。

ログイン・認証が完了しない

症状

• ブラウザ認証後にターミナルへ戻れない
• 認証済みのはずなのに再ログインを求められる
• 組織・アカウントの選択で止まる
• APIキー利用時に認証エラーが出る

確認順

1. 利用しているのがClaudeの対象プランか、API従量課金かを確認
2. ブラウザとターミナルで意図したアカウントを使っているか確認
3. VPN、プロキシ、ファイアウォール、SSL検査の変更有無を確認
4. システム時刻が大きくずれていないか確認
5. 組織管理アカウントなら、管理者の利用許可とポリシーを確認

APIキーをエラー文、スクリーンショット、チャットへ貼らないでください。漏えいが疑われる場合は、組織の手順に従ってキーを失効・再発行し、ログを確認します。

料金と認証方式の違いは、

で確認できます。

Permission denied・操作が承認されない

「権限エラー」は一種類ではありません。

やってはいけない解決

• 原因を確認せず全ファイル・全コマンドを許可する
• 承認回避の危険モードを日常利用する
• システム全体へ広い書き込み権限を付ける
• 本番用の強い資格情報へ置き換える

まず対象ファイルと必要な操作を一つに絞ります。設定の自己点検にはセキュリティ設定チェッカー、詳細には

を利用してください。

日本語入力・文字化け・表示崩れ

切り分け

1. Claude Codeを起動していない同じターミナルで日本語を入力・表示できるか
2. ファイル自体の文字コードがUTF-8か
3. ターミナル、フォント、IME、ロケールのどこで崩れるか
4. WindowsネイティブとWSLのどちらで発生するか
5. 特定ファイルだけか、すべての出力か

日本語で応答させる指示と、端末の文字コード問題は別です。CLAUDE.mdに「日本語で回答」と書いても、ターミナル設定の文字化けは直りません。OS別の確認は、

を参照してください。

MCPサーバーが接続できない・ツールが見えない

主な原因

• 設定したスコープやファイルが想定と違う
• 起動コマンドまたはパッケージが見つからない
• 必要な環境変数がプロセスへ渡っていない
• 認証・OAuthが完了していない
• ネットワーク、プロキシ、DNS、証明書で失敗している
• MCPサーバーとクライアントのログに実エラーがある

確認順

1. /mcpで認識・接続状態を確認
2. 設定スコープと設定ファイルの場所を確認
3. 起動コマンドを秘密情報なしで単独確認
4. 必要な環境変数の「存在」だけを確認し、値は出力しない
5. 接続先の公式ステータスとネットワーク制限を確認
6. サーバーログを保存し、最初の失敗箇所を読む
7. 新しく追加したMCPだけを無効化して再現性を比較

秘密情報を.mcp.jsonへ直書きしたり、ログへ表示したりしないでください。詳しい設定は、

を参照してください。

コンテキストが長い・指示を忘れる・応答が不安定

確認すること

• /contextで何が読み込まれているか
• 長いCLAUDE.mdに重複・矛盾がないか
• 一つの会話に複数の目的を混ぜていないか
• 大量ログや生成物を毎回読み込ませていないか
• 既に完了した調査を会話へ残し続けていないか

対処

1. 目的、対象、完了条件を一つに絞る
2. 長いログは要点とファイル場所だけを残す
3. CLAUDE.mdを重要な指示中心に短くする
4. 必要に応じて/compactを使い、要約後の前提を確認する
5. 独立した調査はSubagentへ分けることを検討する

CLAUDE.mdの整理には、

と無料ジェネレーターを使えます。

利用上限・料金・トークンの問題

症状

• 利用上限に達した表示が出る
• 想定より早く利用枠を消費する
• API請求が予算を超える
• Pro・MaxとAPIの関係が分からない

確認順

1. /statusなど提供される利用状況表示を確認
2. 対象プランかAPIキー利用かを確認
3. 長い会話、大きなコードベース、利用モデル、並列処理を確認
4. APIの場合は入出力トークン、キャッシュ、長いコンテキスト等の料金条件を確認
5. 組織では利用者・業務・費用を同じ単位で記録

利用上限に達しただけで、自動的にAPI従量課金へ切り替わるとは限りません。契約と設定を確認してください。料金シミュレーターは予算の概算に使えますが、実請求は公式管理画面を基準にします。

Hooksや設定変更後に動かなくなった

特定プロジェクトだけ失敗する場合は、直前に追加した設定、Hooks、MCP、Skillを一つずつ切り分けます。

1. 変更前後の設定差分を保存する
2. エラーが起きる最小操作を決める
3. 新規追加した一要素だけを無効化して再実行
4. 改善したら、その要素のコマンド・権限・入出力を確認
5. 改善しなければ元へ戻し、次の要素を調べる

設定ファイル全体を消すのではなく、バージョン管理やバックアップを使って差分単位で戻してください。ユーザーの既存変更を上書きしないことも重要です。

アップデート後に挙動が変わった

1. claude --versionを記録
2. 公式CHANGELOGと既知の問題を確認
3. 同じ指示・同じ入力で再現するか確認
4. プロジェクト固有設定なしの小さな環境と比較
5. 仕様変更か回帰かを分け、再現手順を作る

「昨日まで動いた」だけでは調査できません。バージョン、OS、最小入力、期待結果、実結果をそろえます。

公式サポートへ渡す再現情報

件名：短い症状

環境：OS / ターミナル / Claude Codeバージョン
発生時刻とタイムゾーン：
再現手順：1, 2, 3
期待した結果：
実際の結果：
毎回再現するか：
空の作業フォルダでも再現するか：
直前の変更：
実施済みの確認：
エラー文：秘密情報を除外

スクリーンショットやログには、APIキー、トークン、メール、組織名、リポジトリURL、ローカルユーザー名、顧客データが含まれる可能性があります。共有前に必ず確認してください。

症状別の次のページ

公式情報・最終確認

• Anthropic公式：Claude Code troubleshooting（最終確認：2026年8月16日）
• Anthropic公式：Claude Code overview（最終確認：2026年8月16日）
• Anthropic公式：Claude Code settings（最終確認：2026年8月16日）
• Anthropic公式：Claude Code MCP（最終確認：2026年8月16日）
• Anthropic公式：Claude Code memory（最終確認：2026年8月16日）