Claude Code でよく出るエラー5選と即解決策

「またこのエラーか」と思いながら同じ問題を何度も調べた経験、きっとあるのではないでしょうか。Claude Code を日常的に使っていると、ある程度のパターンで同じエラーに遭遇します。そのたびにドキュメントをさかのぼるのは時間の無駄なので、私がよく遭遇するエラーを5つ、原因と解決策のセットで整理しました。

1. Permission denied — ファイルに触れない

Claude Code がファイルを編集しようとした際に Permission denied が出るケースは、大きく2パターンあります。

パターンA: ファイルオーナーシップの問題

# 所有者を確認する
ls -la 問題のファイル
# -rw-r--r-- 1 root root 1024 May  5 09:00 config.json
 
# 自分に所有権を移す
sudo chown $(whoami) config.json
 
# ディレクトリごと移す場合
sudo chown -R $(whoami) ./プロジェクトフォルダ/

root 所有のファイルを、一般ユーザーとして動く Claude Code が編集しようとすると弾かれます。docker-compose 経由で生成されたファイルや、管理者権限でコピーしたファイルでよく起きます。

パターンB: CLAUDE.md の allowedTools 制限

プロジェクトルートに CLAUDE.md がある場合、allowedTools が制限されていてファイル書き込みが禁止されていることがあります。

# CLAUDE.md の例（書き込み権限がない状態）
allowedTools:
  - Read
  # Write が入っていない！

Write ツールを allowedTools に追加するか、一時的に --dangerously-skip-permissions フラグを使いましょう。本番環境での常用はお勧めしませんが、開発段階では便利なオプションです。

2. RESOURCE_EXHAUSTED — レート制限に当たった

Error: 429 RESOURCE_EXHAUSTED: Resource has been exhausted

API のレート制限に引っかかっています。私がよくやってしまうのは、数千行のコードファイルを読み込んだ後に「このファイル全体を見て改善点を挙げて」と聞くパターン。一度のリクエストで大量トークンを使うので、制限にすぐ当たります。

対処1: /compact でコンテキストを圧縮する

Claude Code 内で /compact を実行すると、会話履歴を要約してトークン使用量を削減できます。長いセッションで詰まったらまずこれを試してください。

対処2: 必要な部分だけを渡す

# ❌ ファイル全体を読み込む（トークン大量消費）
/read src/utils/largeHelpers.ts
 
# ✅ 問題のある関数の行番号を指定して絞る
# 「src/utils/largeHelpers.ts の 45〜90行目だけ見てください」

全ファイルを渡すより「この関数だけ見て」と絞る方が、精度も上がり制限にも当たりにくくなります。

対処3: 60秒待つ

レート制限は通常60秒でリセットされます。焦ってリトライを重ねるとかえって積み重なるので、少し席を立って戻ってくるくらいがちょうど良いです。

3. MCP server not found — MCPサーバーが認識されない

Error: MCP server 'filesystem' not found or failed to start

設定したはずの MCP サーバーが認識されない場合、原因の8割は設定ファイルの記述ミスです。

# macOS の設定ファイルを確認する
cat ~/.claude/claude_desktop_config.json

最もよくある間違いは command に npm パッケージ名を直接書いてしまうことです。

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/username/projects"]
    }
  }
}

上記は mcp-server-filesystem というコマンドをシステムから探しに行きますが、グローバルインストールしていない限り見つかりません。npx 経由で実行する書き方に直してください。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

設定を変更したら Claude Code を完全再起動 してください。設定ファイルは起動時にのみ読み込まれます。

4. Context window exceeded — コンテキストが溢れた

Error: This model's maximum context length is 200000 tokens.
Your request has exceeded the limit.

長時間セッションや、大きなファイルを複数読み込み続けると発生します。コンテキストが溢れて「また最初からか…」となる瞬間の落胆は何度経験してもつらいものです。

予防策1: 定期的に /compact を使う

10〜20回のやりとりが続いたら、作業の切れ目に /compact を挟んで要約させましょう。重要なコンテキストは保持しつつ、不要な詳細を圧縮してくれます。

予防策2: CLAUDE.md に前提を書いておく

## プロジェクト概要
このリポジトリは〇〇をするためのNext.jsアプリです。
 
## 現在の作業
認証機能を実装中。JWT + Refresh Token 方式を採用予定。
 
## コード規約
- TypeScript strict モード
- コンポーネントはfunctionベース
- CSS は Tailwind CSS

新しいセッションでも CLAUDE.md があれば前提を素早く共有できます。コンテキストが溢れた後の立ち上がりがずいぶん速くなります。

5. Bash command failed — コマンドが失敗する

Error: Tool call failed: bash command failed with exit code 1

Claude が実行しようとしたシェルコマンドが失敗したというエラーです。Claude 自体の問題ではなく、実行環境側の問題がほとんどです。

よくある原因: PATH が引き継がれない

Claude Code のシェルセッションでは、.zshrc や .bashrc で設定した PATH が反映されないことがあります。

# Claude が実行しようとしたコマンド
python manage.py migrate
 
# 実際は python3 だった、あるいは venv が有効でなかった

解決策は、Claude Code に対して「python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt をこの順で実行してください」のように、完全なセットアップ手順を明示することです。コマンド名の曖昧さをなくすだけでスムーズになります。

よくある原因: sudo が必要なコマンド

セキュリティ上の理由から、Claude Code は sudo を必要とするコマンドが制限されています。その場合はターミナルで手動実行して、続きを Claude Code に任せる形が現実的です。

5つのエラーパターンを頭に入れておくと、詰まった瞬間に「これはあのパターンだ」と切り替えられるようになります。特に MCP 設定ファイルの記述ミスと、コンテキスト窓の管理は、知っているかどうかで作業効率がかなり変わります。

まずは /compact を意識的に使う習慣から始めてみてください。それだけでコンテキスト溢れの頻度がかなり減るはずです。