Troubleshooting

概要

Claude Code の起動後に起きるパフォーマンス・安定性・検索の問題への対処。インストールやログインの問題は別ページ（troubleshoot-install / errors）が扱う。

仕様

症状別の参照先

症状	参照先
`command not found`、インストール失敗、PATH の問題、`EACCES`、TLS エラー	Troubleshoot installation and login
更新・インストールのダウンロードが `The connection dropped while downloading the update` / `aborted` で失敗	Error reference
ログインループ、OAuth エラー、`403 Forbidden`、"organization disabled"、Amazon Bedrock / Google Cloud's Agent Platform / Microsoft Foundry の認証情報	Troubleshoot installation and login
設定が反映されない、hooks が発火しない、MCP サーバーが読み込まれない	Debug your configuration
`API Error: 5xx`、`529 Overloaded`、`429`、リクエスト検証エラー	Error reference
`model not found` / `you may not have access to it`	Error reference
VS Code 拡張が接続しない・Claude を検出しない	VS Code integration
VS Code や SDK アプリでの `Claude Code process exited with code 1`	Error reference
JetBrains plugin / IDE が検出されない	JetBrains integration
高 CPU / メモリ、応答が遅い、ハング、検索がファイルを見つけない	下記「パフォーマンスと安定性」

どれに当たるか不明な場合は Claude Code 内で /doctor を実行する。インストール・設定・拡張・コンテキスト使用量を自動チェックし、確認のうえ適用できる修正を提案する
claude が起動しない場合はシェルから claude doctor を実行する
MCP サーバーの状態確認は /mcp

高 CPU / メモリ使用

/compact を定期的に使ってコンテキストサイズを減らす。Not enough messages to compact. が返る場合は要約するにはターン数が少なすぎる（大きな貼り付け 1 回でコンテキストが埋まった場合にも起こる）
大きなタスクの合間に Claude Code を終了・再起動する
大きなビルドディレクトリを .gitignore に追加する
claude --safe-mode で再起動し、plugin / MCP サーバー / hook が原因かを確認する。セッション中はすべてのカスタマイズを無効化する

/heapdump:

上記でもメモリ使用量が高いままなら /heapdump を実行する。~/Desktop に 2 ファイルを書き出す
- <session-id>.heapsnapshot（JavaScript heap snapshot）
- <session-id>-diagnostics.json（メモリ内訳）
コマンドメニューには表示されないため、全文を入力する
Linux で Desktop フォルダが無い場合はホームディレクトリに書き出される
会話にも要約が出力される。resident set size、JS heap、array buffers、計上外の native memory、および検出されたリーク指標（メモリ増加率が高い、open handle 数が異常に多い等）を表示する。メモリの大半が JS heap にあるか native memory にあるかも示す
報告する場合は GitHub issue に -diagnostics.json のみを添付する
自分で調べる場合、JS heap が大半なら Chrome DevTools の Memory → Load で .heapsnapshot を開き retained size でソートする

ターミナルで大きなテーブルが切れる

200 行を超える Markdown テーブルは先頭 200 行を表示し、続けて … N more rows not shown の行を出す
制限されるのは表示だけで、テーブル全体は会話に残り、/copy は全行をコピーする
v2.1.208 より前は全行を描画していたため、非常に大きなテーブルを含むセッションを resume すると再描画で停止することがあった

auto-compaction の thrashing エラー

Autocompact is thrashing: the context refilled to the limit... は、自動 compact は成功したがファイルやツール出力が直後に何度もコンテキストを埋め直した状態。無駄な API 呼び出しを避けるため Claude Code は再試行を止める。

大きなファイルは行範囲や関数単位など、小さく分けて読ませる
大きな出力を落とす focus を付けて /compact を実行する（例: /compact keep only the plan and the diff）
大きなファイルの作業を subagent に移し、別のコンテキストウィンドウで動かす
それ以前の会話が不要なら /clear を実行する

ハング・フリーズ

Ctrl+C で現在の操作のキャンセルを試みる
反応が無ければターミナルを閉じて再起動する

再起動しても会話は失われない。同じディレクトリで claude --resume を実行すると再開できる。

エディタ統合ターミナルでの文字化け

VS Code / Cursor / Devin Desktop の統合ターミナルで文字が箱・にじみ・誤ったグリフになる場合、ターミナルの GPU レンダラーが原因の可能性が高い
Claude Code 内で /terminal-setup を実行すると terminal.integrated.gpuAcceleration が "off" に設定される。エディタ設定で手動設定してウィンドウをリロードしてもよい

検索が機能しない

Search ツール、@file メンション、カスタム agent、カスタム skill がファイルを見つけない場合、同梱の ripgrep バイナリが動作していない可能性がある
プラットフォームの ripgrep パッケージをインストールする
- macOS: brew install ripgrep
- Ubuntu/Debian: sudo apt install ripgrep
- Alpine: apk add ripgrep（community リポジトリ）
- Arch: pacman -S ripgrep
- Windows: winget install BurntSushi.ripgrep.MSVC
USE_BUILTIN_RIPGREP を 0 に設定する（シェルの環境変数、または settings.json の env ブロック）
反映確認は claude doctor を実行し、Search 行が OK (bundled) ではなくシステム ripgrep のパスを示すこと

WSL での検索が遅い・不完全

WSL でファイルシステムをまたぐ場合のディスク読み取り性能低下により、期待より少ないマッチしか返らないことがある。検索自体は機能する
この場合 claude doctor は Search を OK と表示する
対処: ディレクトリやファイル種別を指定して検索範囲を狭める / プロジェクトを Linux ファイルシステム（/home/）に置く / WSL ではなく Windows ネイティブで動かす

さらにヘルプを得る

/doctor でセットアップ確認、/mcp で MCP サーバー状態確認
/feedback で Anthropic に直接報告
GitHub リポジトリの既知の問題を確認
Claude に直接機能を尋ねる（Claude はドキュメントへの組み込みアクセスを持つ）

設定

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

制約・注意点

.heapsnapshot にはプロセス内の全文字列（会話全体と認証情報を含む）が入る。公開 issue に添付したり共有したりしてはならない