Claude Codeでよくあるエラー10選 — 起動失敗から認証・MCP・権限まで実機で踏みやすい順に対処

はじめに

Claude Codeを業務で使い込んでいると、月に何度かは何らかのエラーに当たります。本記事では、サポート / コミュニティで頻出する10種のエラー を、実機で踏みやすい順に整理し、判定方法と現実的な対処手順を示します。

迷ったら、まずは claude doctor で環境診断、次に claude --version で最新版か確認、さらに claude update でアップデートを試す — これだけで4割以上のエラーは解消します。

1. 起動時に「認証エラー」「Sign in failed」

最も頻出のエラー。原因はいくつかあります。

FreeプランではClaude Codeは起動できません。Pro / Max / Team / Enterpriseいずれかのサブスクリプション、またはConsole のAPI keyが必要です。利用条件はClaude Code完全ガイドに整理しています。

2. WindowsでVS Code拡張が起動しない / activate failed

Windows + VS Code拡張 + 特定バージョン(v2.1.129系)で発生していたバグです。createRequire ポリフィルがバンドルSDK内のビルドパスをハードコードしていた問題で、v2.1.131で修正されました。

claude update
# v2.1.131 以降になっていれば解消

該当バージョン以前のままで止まっている場合は、まず claude update を試します。それでも直らない場合は、Claude Code本体を一旦アンインストールしてNative Installで入れ直すと解決することがあります。

3. --resume で「tool_use ids were found without tool_result blocks」

長期セッションを --resume で再開しようとして起動しないエラー。v2.1.85以前に作ったセッションが、それ以降のClaude Codeで再開できなくなる現象が一時的にありました。v2.1.86で旧フォーマットの後方互換が補修されたため、claude update で解消します。

claude update           # v2.1.86 以降にする
claude --resume          # セッションを選んで再開

それでも該当セッションだけ起動しない場合は、~/.claude/projects/<encoded-cwd>/<session-id>.jsonl が破損している可能性があります。新規セッションは問題なく起動できる、という切り分けで原因を絞り込めます。

4. MCPサーバ(stdio経由)でメモリが10GB+ に膨張

MCPサーバが標準出力にプロトコル外のデータを書き続けると、Claude Code側がそれをバッファし続けてメモリが線形に膨らむバグです。v2.1.132で修正されました。

判定:

ps aux | grep claude     # RSS が 5GB+ ならこのバグの疑い

対処:

1. claude update でv2.1.132以降にする
2. それでも膨らむ場合は、自前MCPサーバーが console.log を console.error に直す(stdoutを汚さない)
3. MAX_MCP_OUTPUT_TOKENS 環境変数でMCP出力の上限を絞る

詳細はMCP実用ガイドの「権限とセキュリティ」節を参照。

5. SSE/HTTP系MCPサーバが「無限ハング」

接続が応答途中で切れたとき、ツール呼び出しが終わらない現象。v2.1.110で修正されました。claude update でほぼ解消します。

それでもハングする場合はMCPサーバ側のレスポンス形式が壊れている可能性があり、/doctor で重複定義(同じサーバをuser / project / localで別エンドポイント定義している)が無いか確認します。

6. レート上限に頻繁に当たる(Pro / Maxでも)

Proプランで多発する場合はMaxプランへのアップグレードが現実的な解決策です。料金プラン選び方ガイドで利用パターン別の境目を整理しています。

ただし、2026-05-06の利用上限引き上げ発表以降、Pro / Maxの5時間ウィンドウ上限は2倍化されているため、以前より長く使えるはずです。それでも当たる場合は、Opus 4.7をSonnet 4.6に切り替えると上限の扱いが変わります。

/model claude-sonnet-4-6

7. Bashツールが「サンドボックス遮断」エラー

Sandboxed Bash Tool有効環境(macOS Seatbelt / Linux Bubblewrap)で発生します。サンドボックス内では特定のシステム呼び出しが制限されるため、brew install や sudo 系のコマンドは実行できません。

対処:

• 一時的に許可: claude --permission-mode acceptEdits でサンドボックスを緩める
• 恒久的に許可: .claude/settings.json の sandbox.network.allowedDomains sandbox.filesystem.allowReadPaths で個別パスを明示
• そもそもBash Sandboxを無効化: sandbox.bash: false

設計思想はClaude Codeサンドボックス設計で詳しく扱っています。

8. /doctor で「LSP did not respond in time」

重い言語サーバー(rust-analyzer / gopls / TypeScript Language Server)が冷えた状態から起動するときに出る警告。モノレポの初回起動で踏みやすい現象です。

対処:

{
  "lsp": {
    "startupTimeout": 60000
  }
}

startupTimeout の指定はv2.1.50で導入されました。デフォルトの数秒から60秒に伸ばすと、初回起動の安定度が大きく上がります。

9. メモリリーク(長時間セッションでRSSが増え続ける)

Claude Codeの長時間セッション(日をまたぐインタラクティブ運用 / Agent Teams大量並列)でRSSが増え続ける現象。これまでに以下のリリースで複数のリークが修正されています。

• v2.1.50: TaskOutput残留 / CircularBuffer未解放 / shell ChildProcess / LSP diagnosticほか7種
• v2.1.69: 6系統のメモリリーク一掃(103項目の超大型メンテ)
• v2.1.116: 起動・再開・MCP接続のメモリ使用量を67% 削減
• v2.1.121: 多GB級のメモリリーク3件解消

claude update で最新版にするだけで多くのケースは解消します。それでも増え続ける場合は、再現できる最小ケースを切り出してGitHubのanthropics/claude-code Issues に報告するのが有効です。

10. .claude/settings.json を編集しても反映されない

設定キーが間違っている / 配置場所が間違っている、の2パターンが大半です。

判定:

claude doctor                                # 設定ファイルの認識状況を表示
cat ~/.claude/settings.json                  # ユーザーレベル設定
cat .claude/settings.json                    # プロジェクトレベル設定

対処:

• スキーマエラーは claude doctor で検出される
• 設定キーの一覧はClaude Code設定完全ガイドで網羅
• ~/.claude.json にしか入らない設定(autoConnectIde 等)を settings.json に書いてもエラーにならず無視されるので注意
• Managed Settings(Enterprise)がuser / projectの値を上書きする場合がある

デバッグの一般的な手順

エラーの原因が分からないとき、以下の順で切り分けると当たりやすいです。

1. claude doctor: 環境全体を診断、警告 / エラーがあれば表示
2. claude --version + claude update: 最新版に揃える(過去のバグが直っている可能性が高い)
3. ~/.claude/cache/changelog.md または公式changelog で関連バージョンを検索:症状を直したリリースが見つかることが多い
4. claude --bare で最小ランタイムを試す:Skills / Hooks / MCPの影響を切り分け
5. /clear + /compact でセッション状態をリセット
6. CLAUDE.mdの読み込みを止める: CLAUDE_CODE_SIMPLE=1 claude で素の状態に戻す
7. それでも解消しない:最小再現ケースを作ってGitHub Issuesに報告

まとめ

ほぼすべてのエラーは「claude doctor → claude update → 関連バージョンのchangelog確認」の3ステップで対処方針が立ちます。Claude Codeは更新頻度が高い(週に複数回のリリース)ため、遭遇したエラーは過去のリリースで既に修正されている確率が経験的に最も高いです。

エラー対処を体系的に減らすには、CI連携と組み合わせたClaude CodeをGitHub Actionsに組み込む実用ガイド、設定面はClaude Code設定完全ガイド、セキュリティ面はClaude Codeセキュリティ・権限ガイドを併読してください。