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

はじめに

Claude Codeを業務で使い込んでいると、月に何度かは何らかのエラーに当たります。本記事は、サポートやコミュニティで頻出する10種のエラーを、踏みやすい順に並べ、判定方法と対処手順を示します。インストール自体が完了しない・claudeコマンドがまだ動かない段階のエラーは対象外で、Claude Codeインストールエラーの切り分けチェックリストで扱っています。

迷ったら、まず claude doctor で環境を診断し、claude --version で版を確かめ、claude update で更新します。Claude Codeは更新頻度が高く、後述のとおり多くの不具合は特定バージョンで直っています。

v2.1.289で、設定ファイルのない一時ディレクトリから claude doctor を実行すると次のように表示されました(ユーザー名とパスは伏せています)。インストール方法・自動更新の状態・直近の更新結果が1画面で分かります。

$ claude doctor
Claude Code doctor
 
Running: native (2.1.289)
Platform: darwin-arm64
Path: ~/.local/share/claude/versions/2.1.289
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: success
Managed settings (remote): not fetched — requires an Enterprise or Team subscription
Organization policy: not applicable to Pro and Max accounts
 
No installation issues found.

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

最も頻出のエラーです。

ログインしたはずなのに再度求められるときは、資格情報の保存先が手がかりです。Linuxでは ~/.claude/.credentials.json(権限0600)、Windowsでは %USERPROFILE%\.claude\.credentials.json に保存されます。macOSは暗号化されたKeychainが標準ですが、SSHセッションなどでKeychainが書き込みを拒否すると、Linuxと同じ ~/.claude/.credentials.json に保存されます。CLAUDE_CONFIG_DIR を設定している場合は、このファイルもKeychainのエントリも設定先のディレクトリ単位になります。そのため、CLAUDE_CONFIG_DIR が違うシェルからは別のログイン状態に見えます。

FreeプランではClaude Codeは起動できません。Pro / Max / Team / Enterpriseのいずれかのサブスクリプション、またはConsoleのアカウントが必要です。利用条件はClaude Codeとは — できること・料金・使い方に整理しています。

認証エラーとは別に、「Not logged in · Please run /login」と出るケースもあります。資格情報の不在、環境変数の見落とし、バックグラウンドセッション特有の事情など原因が複数あり、切り分け方はClaude Code「Not logged in」エラーの原因と対処法にまとめています。

認証自体は通っているのに接続が失敗する「Unable to connect to API」は、上記とは原因が別です。ConnectionRefusedやENOTFOUNDなどエラーコード別の見分け方は「Unable to connect to API」の原因と対処 — Claude Codeで扱っています。

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

WindowsのVS Code拡張が起動しなかった不具合は、v2.1.131で修正されました。同梱SDK内のビルドパスがハードコードされていた問題(createRequire ポリフィルのバグ)です。

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

それより古い版で止まっている場合は、まず claude update を試します。

VS Code拡張やAgent SDKアプリが「Claude Code process exited with code N」を返す、終了コード以外の切り分け方は「process exited with code N」の対処にまとめています。

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

長期セッションを --resume で再開しようとして失敗するエラーです。v2.1.85以前に作ったセッションが対象で、v2.1.86の変更履歴に「v2.1.85より前に作成したセッションで --resume が失敗する問題を修正」と載っています。

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

それでも特定のセッションだけ起動しない場合は、~/.claude/projects/<encoded-cwd>/<session-id>.jsonl が破損している可能性があります。新規セッションは問題なく起動できるなら、原因はそのセッションの記録側に絞れます。巨大なセッションの再開が遅いだけなら別の話で、v2.1.116で40MB超のセッションの /resume が最大67%速くなりました。

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

stdioのMCPサーバーが標準出力にプロトコル外のデータを書き続けると、メモリが10GB以上に膨らむ不具合がありました。v2.1.132で修正されています。同系統として、HTTP/SSEのMCPサーバーが同種のデータを流し続けるケースも、v2.1.139でSSEフレームあたり16MBに制限されました。

判定は ps で行います。

ps aux | grep claude     # RSS が数GB以上に膨らんでいたらこのバグの疑い

対処は次の順です。

1. claude update でv2.1.132以降にする
2. それでも膨らむ場合は、自前MCPサーバーの console.log を console.error に直す(stdoutをプロトコル専用にする)
3. MAX_MCP_OUTPUT_TOKENS 環境変数でMCPツールの応答サイズ上限を絞る(既定は25000トークンで、10,000を超えると警告が出ます)

MCP全般の切り分けはMCP実用ガイドの「つまずいたときの切り分け方」でも扱っています。

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

接続が応答の途中で切れたとき、ツール呼び出しが終わらない現象です。v2.1.110の変更履歴に「SSE/HTTPトランスポートで、応答の途中に接続が切れるとMCPツール呼び出しが無期限にハングする問題を修正」とあります。claude update でこの版以降にします。

それでもハングする場合は、MCPサーバー側のレスポンス形式が壊れている可能性があります。/mcp で各サーバーの定義元を見て、同じサーバーをuser / project / localで別エンドポイントとして定義していないかを確かめます。

6. 上限に当たったときのメッセージの見分け方

「レート上限」と一口に言っても、Claude Codeが出すメッセージは出どころで4種類に分かれます。見分けないと、モデルを替えても直らない、プランを上げても直らないといった遠回りになります。

429が出たときは、/status で有効な資格情報が想定どおりか確認します。環境変数 ANTHROPIC_API_KEY が残っていると、サブスクリプションではなく低ティアのキーに流れることがあります。並列度を下げる手段として、CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY を下げる、サブエージェントの並列実行を減らすといった方法もあります。

一回の大きな作業(大規模なワークフローの並列実行など)が、セッション枠が戻る前に週次枠まで使い切ることもあります。Pro / Maxの5時間枠は2026-05-06に引き上げられました。プランごとの使用量の境目は料金プラン選び方ガイドにまとめています。

似た症状に見えても、429やoverloadedとは原因が別の「Request timed out」もあります。自動リトライの範囲やAPI_TIMEOUT_MSの調整方法はClaude Code Request timed outエラー — 原因と対処法にまとめています。

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

サンドボックスが有効な環境では、Bashツールの外向き通信は専用のプロキシを通り、許可ドメインの一覧と照合されます。この一覧は初期状態で空です。対話セッションの手動モードや acceptEdits モードでは、許可外のホストへの通信に許可の確認が出て、Yesを選ぶとそのセッション中は通ります。auto modeでは、コマンド側がホストを列挙し分類器が承認した場合を除き、確認なしで拒否されます。strictAllowlist やmanaged settingsの allowManagedDomainsOnly を使っている場合は確認なしで遮断されます。遮断されると、コマンドの結果に遮断されたホスト名が出るので、Claudeにも何が止まったか分かります。

対処は、範囲の狭い順に次のとおりです。

• 特定のホストだけ通す: .claude/settings.json の sandbox.network.allowedDomains にドメインを足す
• 特定のパスだけ通す: 書き込みは sandbox.filesystem.allowWrite、denyRead で塞いだ領域の再許可は allowRead で指定する
• 特定のコマンドだけサンドボックス外で動かす: sandbox.excludedCommands にパターンを足す
• サンドボックス自体を止める: sandbox.enabled を false にする

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

--permission-mode acceptEdits はサンドボックスを緩める設定ではありません。サンドボックスに阻まれたコマンドをClaudeが dangerouslyDisableSandbox 付きで再試行する場面では、通常モードも acceptEdits モードも「Bash command (unsandboxed)」という確認が出ます。allowUnsandboxedCommands を false にすると、この再試行自体が無効になります。

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

似た拒否として、pkillを実行しようとしたパターンがClaude Code自身のプロセスにも一致すると、実行前にブロックされることがあります。これは会話を巻き込み事故から守るガードで、仕組みと回避策は「pkill Claude Code process」の意味にまとめています。

8. LSPサーバーの起動が間に合わない

rust-analyzer、goplsのような重い言語サーバーは、コールドスタート時の初回起動に時間がかかります。モノレポで特に踏みやすい現象です。

LSPサーバーの起動待ち時間は、プラグインのLSP設定にある startupTimeout(ミリ秒の正の整数)で指定します。.claude/settings.json に lsp キーを置いても効きません。プラグインの .lsp.json で、サーバーごとに書きます。

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": { ".go": "go" },
    "startupTimeout": 60000
  }
}

startupTimeout はv2.1.50で追加されました。lspServers の設定は厳密に検査され、未知のキーがあるとプラグインが読み込まれません。綴りを間違えたときは、設定が無視されるのではなくプラグインごと動かなくなります。

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

長時間セッションや大量並列でRSSが増え続ける現象には、複数のリリースで修正が入っています。

• v2.1.50: 長いセッションでのリーク修正が複数
• v2.1.69: SDK / CCRの長時間セッションでの会話保持、巨大な未追跡バイナリを含むコミット時の数GB級のメモリ急増など
• v2.1.121: 多数の画像を処理するセッションでの数GB級のメモリ増加など

まず claude update で最新版にします。それでも増える場合は、公式のトラブルシューティングが次の手順を示しています。

.heapsnapshot には会話全文と資格情報が含まれるため、公開のIssueには添付しません。GitHubのanthropics/claude-code Issuesには、診断JSON(-diagnostics.json)だけを添付します。こちらには会話内容も資格情報も入りません。

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

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

判定:

claude doctor                                # インストール状況の診断
cat ~/.claude/settings.json                  # ユーザーレベル設定
cat .claude/settings.json                    # プロジェクトレベル設定

対処:

• スキーマエラーは /doctor で検出される
• 設定キーの一覧はClaude Code設定完全ガイドで網羅
• ~/.claude.json はClaude Codeが自分用に書くファイルで、ログイン状態やMCPサーバー設定などが入ります。ここにしか置けないグローバル設定を settings.json に書いても、エラーにならず無視されるので注意
• Managed Settings(Enterprise)がuser / projectの値を上書きする場合がある

デバッグの一般的な手順

エラーの原因が分からないとき、次の順で切り分けます。

なお、ここまでは環境側の不具合を切り分ける手順です。自分のコードのバグを直す場面での情報の渡し方はClaude Codeデバッグの精度は、渡す情報の質で決まるで扱っています。

まとめ

第2〜5節と第9節は特定バージョンで直った不具合が中心で、版を揃えるだけで解消することがあります。残る第6・7・8・10節は、上限の種類、サンドボックスの許可範囲、LSPの起動待ち時間、設定の置き場所といった設定・環境側の問題です。どちらに当たるかを先に見分けると、遠回りが減ります。

エラー対処を体系的に減らすには、CI連携と組み合わせたClaude CodeをGitHub Actionsに組み込む実用ガイド、設定面はClaude Code設定完全ガイド、セキュリティ面はClaude Codeセキュリティ・権限ガイドを併読してください。こうしたエラーの頻度や解消の速さが導入判断に見合うかはClaude Codeの評判は実際どうか — 強みと弱みを公式情報で検証で公式情報をもとに検証しています。