Claude Codeトラブルシューティング・FAQ｜よくあるエラー20選と対処法

Claude Code を使っていると、ある日突然「動かない」「エラーが出る」状況に直面することがある。原因は環境依存、API側のメンテナンス、ファイル権限、ネットワーク――要因が多岐にわたるため、初心者にとって何から疑えばいいか分からないのが最大の壁だ。

この記事では、実際の現場で頻発する20種類のトラブルと、その対処法を、症状別に整理する。トラブル発生時はここを最初に参照すれば、9割の問題が解決するはずだ。

カテゴリA:インストール・起動関連(5件)
カテゴリB:API・課金関連(4件)
カテゴリC:コード生成・実行(4件)
カテゴリD:Sub-Agents・拡張機能(3件)
カテゴリE:Git・GitHub連携(2件)
1. 17. /commit で「コミットできるものがない」
2. 18. /pr で GitHub認証エラー
カテゴリF:パフォーマンス(2件)
1. 19. レスポンスが極端に遅い
2. 20. メモリ不足エラー
トラブルシュート時の鉄則
まとめ
関連記事

カテゴリA:インストール・起動関連(5件)

1. claude: command not found

原因: パスが通っていない、または npm install -g が失敗している

対処:

which claude で実態確認
npm list -g @anthropic-ai/claude-code でインストール状況確認
npm の global path を確認: npm config get prefix
必要なら再インストール: npm uninstall -g @anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code

2. 起動時に Node.js バージョンエラー

原因: Node.js が18未満

対処: nvm/fnm で最新Nodeに切り替え。node -v が18以上であることを確認。

3. ログインブラウザが開かない

原因: デフォルトブラウザの設定問題、または xdg-open 不在(Linux)

対処: ログイン URL をターミナルに表示してくれるので、手動でコピペして別ブラウザで開く。

4. ログイン後 Claude Code に戻らない

原因: 認証後のリダイレクトがブロックされている

対処: ターミナルウィンドウに戻って Enter キーを押すと進行することが多い。または claude --logout && claude で再試行。

5. アップデート後に起動しなくなった

原因: 旧設定ファイルとの非互換

対処: ~/.claude/ ディレクトリをバックアップ後に削除して再ログイン。

カテゴリB:API・課金関連(4件)

6. 429 Rate Limit Exceeded

原因: 短時間に多すぎるリクエスト

対処: 数分待つ。それでも頻発するなら Pro → Max プランに切り替え検討。

7. 403 Forbidden

原因: 認証期限切れ、プラン未契約

対処:

claude --logout && claude で再ログイン
Anthropic アカウントで Pro プラン契約状態を確認

8. コスト表示が予想より高い

原因: 大規模なコードベース調査で大量トークン消費

対処:

/cost で現状を把握
/clear でコンテキスト履歴をクリア
/compact で履歴圧縮
大規模調査は explore Sub-Agent に任せると経済的

9. API エラー: model_not_found

原因: 古いバージョンのClaude Codeが、廃止されたモデルを参照している

対処: npm update -g @anthropic-ai/claude-code で最新版へ。

カテゴリC:コード生成・実行(4件)

10. コード生成が止まる(数分応答なし)

原因: 大規模リファクタリングで処理時間がかかっている

対処:

5〜10分は待ってみる(長時間タスクの可能性)
改善されないなら Ctrl+C でキャンセル
指示をより具体的に分割して再投入

11. 生成されたコードが既存規約を無視する

原因: プロジェクト固有の規約が /memory に登録されていない

対処:

CLAUDE.md ファイルをプロジェクトに作成し、規約を明記
/memory で重要なルールを登録
個別指示で具体的に「ESLint規約に従って」と明示

12. 「実行していい?」が頻発して進まない

原因: ファイルアクセス権限が事前許可されていない

対処: .claude/settings.json で permissions.allow に頻用パスを追加

{
  "permissions": {
    "allow": ["Read(**)", "Write(src/**)", "Bash(npm test:*)"]
  }
}

13. テスト実行で command not found が出る

原因: シェル環境が Claude Code から見えない PATH 問題

対処: 絶対パスで指示するか、.claude/settings.json の env でPATHを明示。

カテゴリD:Sub-Agents・拡張機能(3件)

14. Sub-Agent が起動しない

原因: 設定ファイル形式エラー、または agent name の不一致

対処: .claude/agents/<name>.md の frontmatter (name, description) を確認。/agents で認識されているか確認。

15. Skill が呼び出せない

原因: ファイル配置ミス(.claude/skills/ 直下にあるか)

対処: ディレクトリ構造を確認。SKILL.md ファイル名は固定で大文字。

16. Plugin が認識されない

原因: インストール完了後のセッション再起動が必要

対処: Claude Code を一度終了して再起動。または /plugins で状態確認。

カテゴリE:Git・GitHub連携(2件)

17. /commit で「コミットできるものがない」

原因: ステージング前の変更がない

対処: git status で変更を確認。/commit は変更がない時は実行しない安全設計。

18. /pr で GitHub認証エラー

原因: gh CLI が未認証

対処: gh auth login を先に実行して GitHub と認証を済ませる。

カテゴリF:パフォーマンス(2件)

19. レスポンスが極端に遅い

原因の可能性:

ネットワーク不安定
API側の負荷高騰
コンテキストが大きすぎる

対処:

/cost でセッションの状況確認
/compact または /clear で履歴整理
別のセッションで再試行

20. メモリ不足エラー

原因: Node.js のヒープサイズ制限

対処: 環境変数で増加 NODE_OPTIONS="--max-old-space-size=8192" claude

トラブルシュート時の鉄則

症状を正確にメモ(エラーメッセージ、操作、コマンド履歴)
公式 Anthropic Status Page で障害情報を確認
claude --version で最新かどうか確認
再現性確認: 同じ操作で再現するか
最小再現コード: 大規模プロジェクトなら、最小再現用フォルダで切り分け

公式 Discord (anthropic) または GitHub Issues に投稿する際も、この5点が揃っていると解決が早い。

まとめ

Claude Code はまだ進化途中のツールだ。新機能リリース、互換性変更、たまの API障害――そういう「動かない瞬間」は、これからも訪れる。

ここに整理した20件は、現場で実際に観測された頻発トラブル。1〜2回出会うものだから、ブックマークしておく価値がある。

基本機能の理解はClaude Codeとは？仕組み・できること、コマンド全般はClaude Codeの基本コマンドと主要機能、上級TipsはClaude Code上級者向けTips・効率化で深掘りした。