入門
よくあるエラーと対処法
Claude Code利用時によく遭遇するエラーとその解決方法をまとめたトラブルシューティングガイド。
claude-codetroubleshootingerrorsbeginner
コンテキストウィンドウの上限エラー
Claude Code で長時間作業していると、コンテキストウィンドウの上限に達することがあります。
症状: 「コンテキストが長すぎます」「context window exceeded」等のメッセージ
対処法:
/compactコマンドでコンテキストを圧縮- 新しいセッションを開始（
claudeで新規起動） - CLAUDE.md にプロジェクト情報を記録しておけば、新セッションでも文脈を引き継げる
予防策: 大きなタスクは分割し、1セッション1-2タスクに絞る
ビルド/型エラーが解消されない
Claude Code が修正を試みてもビルドエラーが繰り返される場合。
症状: 同じエラーが何度も発生、修正が堂々巡り
対処法:
- エラーメッセージを正確にClaude Codeに伝える（スクリーンショットではなくテキストで）
npx tsc --noEmit 2>&1 | head -20で最初のエラーに集中- 1つずつ修正する（複数エラーを同時に直そうとしない）
- Plan Mode（
--permission-mode plan）で原因分析だけ先に行う
予防策: PostToolUse hook で .ts 編集後に自動型チェックを設定
パーミッションが繰り返し求められる
ツール実行のたびに許可を求められて作業が進まない場合。
症状: 「Allow?」プロンプトが頻繁に表示
対処法:
--permission-mode auto-editで編集を自動許可--permission-mode bypass-permissionsで全許可（信頼できるプロジェクトのみ）settings.jsonのallowedToolsで特定ツールだけ許可
注意: bypass-permissions は信頼できるプロジェクトでのみ使用すること
MCPサーバーに接続できない
MCP サーバーの設定後、ツールが使えない場合。
症状: MCPツールが表示されない、接続エラー
対処法:
claude mcp listで設定済みサーバーを確認- サーバーの実行パスが正しいか確認（
whichコマンド等） - 環境変数（APIキー等）が設定されているか確認
claude mcp remove <name>→claude mcp addで再設定
セッションが突然終了する
長時間のセッションが予期せず終了する場合。
症状: セッションが途中で切断、結果が失われる
対処法:
claude --resumeで最新セッションを再開claude --continueで直前のセッションを継続- 重要な進捗は CLAUDE.md や
#メモリに随時保存
予防策: 大きなタスクの途中でこまめに # でメモリに保存
あわせて読む
- CLAUDE.md でプロジェクトのルールを定義する - プロジェクト設定の基本
- コンパクションでコンテキストを管理する - コンテキスト管理
- パーミッションモードを使い分ける - 権限設定の詳細