Claude Code を業務で使い込むほど、エラーメッセージの読み解きに時間を取られるようになります。一見似た症状でも、発生層（認証・課金・モデル応答・ツール・MCP・Hook）のどこで止まっているかによって、正しい復旧手順は全く異なります。このハンドブックでは、私が実務で遭遇した主要なエラーパターンを症状から逆引きできる形で整理し、それぞれについて「なぜ起きるのか」「どこを見ればいいのか」「どう直すのか」を一段深いところまで掘り下げてまとめました。単なるエラーメッセージ集ではなく、次に同じ症状に遭ったときに、セッションを捨てずに復旧させるための実務資料 として活用いただけます。
章立てと読み方
本稿は 6 章で構成されています。エラーに遭遇したときは、症状から該当章に飛んでください。各項目は「症状 → 起きている場所 → 確認コマンド → 復旧手順」の 4 点セットで書かれています。
- 認証と権限のエラー
- 決済・カード拒否・請求周りのエラー
- 応答停止・未完了・タイムアウト
- ツール実行の失敗（Bash / Read / Edit / Write）
- MCP サーバーと Hook の失敗
- 環境変数・設定ファイルに起因する複合エラー
1. 認証と権限のエラー
認証周りは、Anthropic アカウント と Claude Code CLI の local credential の 2 層で認証状態が保持されています。片方だけ期限切れや不整合を起こすと、一見正常にログインしているように見えるのに特定の操作で突然弾かれる、という症状になります。
症状: Invalid API key で起動時に落ちる
これは CLI が保持しているトークンが期限切れか、別アカウントのトークンに上書きされたときに出ます。~/.claude/credentials.json に保存されている access_token の有効期限を確認し、切れていたら claude logout && claude login を実行します。macOS の場合は Keychain に別の古いトークンが残ることがあり、security delete-generic-password -s "Claude Code" で明示的に削除してからログインし直すと確実です。
症状: You do not have access to this organization と表示される
組織アカウントに招待された直後や、Workspace を切り替えた直後に出やすい症状です。CLI は一度取得したアクセストークンをキャッシュしているため、組織切り替えが反映されません。claude config set workspace <workspace-id> で明示的に切り替えるか、一度ログアウトして再度ログインしてください。
症状: Partner Network の接続で Forbidden が返る
Claude Partner Network からの接続を有効にしている場合、連携先のパートナー ID とワークスペース ID の紐付けが失効していると 403 Forbidden になります。Partner Network ダッシュボードで接続状態を確認し、必要ならパートナー側のアクセス権限を再承認します。Partner Network の連携トークンは Claude 本体のトークンとは別に管理されている点に注意してください。
症状: 2 段階認証の認証コードが届かない
2FA コードが届かないときは、まず Anthropic アカウントに登録しているメールアドレスが現役のものか確認します。法人メールの場合はスパムフィルタで弾かれているケースが多く、IT 部門に no-reply@anthropic.com を許可してもらう必要があることが多いです。Authenticator 経由の場合は時刻ずれで無効になることがあり、スマートフォンの時刻を自動同期に設定し直してください。
2. 決済・カード拒否・請求周りのエラー
私が運営するサイトの検索ログを見ていると、「カードが拒否されました」「決済できない」系の検索が非常に多いです。実際この系統はパターンが多岐にわたり、Anthropic 側ではなくカード会社側で弾かれていることがほとんどです。ここでは順序立てた切り分けを示します。
症状: Your card was declined が繰り返し表示される
最初に確認するのはカード会社側の 3D セキュア設定です。日本の多くのカードは、海外オンライン決済（Anthropic は米国拠点）で 3D セキュアを要求します。カード会社の Web で本人認証サービス（Visa Secure / Mastercard ID Check / J/Secure）を有効にしてください。これだけで解決するケースが最も多いです。
次に、同じカードで過去数分以内に繰り返し試行していないかを確認します。短時間の繰り返し試行はフラグされて弾かれるため、10 分ほど間隔を空けてから再試行してください。
それでも通らない場合は、カードの国際ブランドそのものが Anthropic の決済プロバイダで対応していないケースがあります。JCB・Diners は海外 SaaS の決済で弾かれがちなので、Visa/Mastercard/American Express のカードで再試行することをお勧めします。
症状: Payment failed. Please contact Anthropic と出る
このメッセージは、カード側ではなく Anthropic の決済プロバイダ（Stripe）側で何らかのリスク判定が行われた ときに出ます。VPN 越しの決済、IP と請求住所の国の不一致、特定の匿名プロキシ経由などが引き金になります。VPN を一旦切って、ブラウザのプライベートウィンドウ（Cookie なし）で再度試してください。
症状: サブスクリプションの更新が失敗し、アカウントが restricted になった
自動更新時のカード引き落としが失敗すると、アカウントがしばらく restricted 状態になります。Web コンソールにログインして「Billing → Update payment method」から新しいカードを登録し、手動で更新を再試行します。カード変更後は 30 分から 1 時間ほど反映に時間がかかることがあるので、即座に Claude Code で作業を再開できなくても慌てないでください。
症状: クレジットカードではなく請求書払いにしたい
これは法人契約の機能で、Anthropic のセールスに直接連絡する必要があります。Claude.ai のアカウント設定からではなく、sales@anthropic.com へ利用規模を伝えて交渉します。中小規模でも月額契約であれば請求書払いの選択肢があります。
3. 応答停止・未完了・タイムアウト
応答が途中で止まる症状は前編（無料記事）でも触れましたが、プレミアム版では業務で詰まりがちな複合ケースを含めてより深く扱います。
症状: Response incomplete が Extended Thinking 中に頻発する
Extended Thinking は思考トークンを大量に消費します。思考トークンは通常の応答とは別枠で計上されますが、モデルの内部的な処理時間が長くなるため、途中でストリーミングが切れやすくなります。対処は以下の 3 段階で行います。
まず、/think のレベルを一段落とします。ultrathink で詰まる場合は think hard、think hard で詰まる場合は通常の think に落とします。これで通れば、タスクが単純に思考予算を超えていたと判断できます。
次に、通っても応答が浅い場合は、タスク自体を分割します。「設計と実装を一緒に考えてほしい」という依頼は思考予算を食うので、「まず設計を詰める」→「確定した設計に対して実装する」と 2 ターンに分けます。
最後に、それでも繰り返す場合は ~/.claude/settings.json の thinkingBudget を明示的に設定して上限を制御します。環境によってはデフォルトが大きすぎることがあり、上限を絞った方が安定します。
症状: Tool use timeout でツール呼び出しが止まる
Bash ツールのデフォルトタイムアウトを超える長時間コマンド（大規模テストスイート、モノレポ全体のビルドなど）で起こります。対処は、ツールの呼び出し側でタイムアウトを明示的に伸ばすか、そもそもバックグラウンド実行にしてポーリングする方式に変えます。
具体的には、CLAUDE.md に「時間がかかるコマンドは nohup ... & でバックグラウンドに回し、ログファイルを tail -n 50 で確認すること」と書いておくと、Claude が自律的にこのパターンを使ってくれます。
症状: 出力トークン上限に毎回ぶつかる
長いコード生成で毎回上限に達する場合、max_tokens を大きくすることよりも、出力形式自体をコンパクトにする 方が効果的です。
例えば、大量のファイルを同時に書き換えさせるとき、既存ファイル全体を再出力する指示ではなく、「unified diff 形式で変更箇所だけを出力し、その後 Edit ツールで適用してください」と指示すると、出力トークンが 1/3 以下になり、上限到達を回避できます。Claude Code ではこのパターンを使うと自然な作業になります。
症状: セッションが長時間続いた後に極端に応答が遅くなる
コンテキスト使用率が 85% を超えたあたりから、応答生成そのものが重くなります。これは Claude 側の処理というより、送信するコンテキスト量が単純に大きいためです。
対処は、自動コンパクションを待たずに明示的に /compact するか、重要な未完タスクをメモに書き出してから claude --resume で新セッションに移行します。体感としては、コンテキスト使用率 70% を超えた時点でコンパクションを検討するのが最も安定します。
4. ツール実行の失敗
症状: Bash ツールで command not found が頻発する
Claude Code の Bash ツールは、ログインシェルではなく非対話シェルで起動するため、.bashrc や .zshrc で設定している PATH が読み込まれないことがあります。対処は、プロジェクト直下の .envrc に PATH を書いて direnv を使うか、CLAUDE.md に「which <コマンド> で存在確認してから呼ぶこと」と指示することです。
症状: Edit ツールで old_string not found が連続する
これは Edit ツールが最も失敗しやすいエラーです。原因は空白・改行・タブ文字の不一致で、見た目は同じでも内部のコードが違うと一致しません。
対処は 2 つあります。ひとつは、Claude に直前に Read ツールで該当箇所を読み直させることです。Read の出力をそのまま old_string として使うと、ほぼ確実に一致します。もうひとつは、長い old_string を避け、前後数行を含む短めのユニークな文字列で指定することです。
症状: Write ツールで既存ファイルへの書き込みが拒否される
Claude Code の Write ツールは、既存ファイルへの完全上書きを嫌う設計になっており、先に Read していないファイルへの Write はブロックされます。これは意図された動作で、思わぬ上書きを防ぐための安全機構です。
適切なワークフローは、Write を使う前に必ず Read で現在の内容を取得する、差分がある場合は Edit を使う、完全に新規作成するファイルだけ Write を使う、という使い分けです。
症状: ファイルアップロードが失敗する
Web 版の Claude でファイルアップロードが「Failed to upload」と出る場合、多いのはサイズ超過（20 MB 以上）と MIME タイプの不一致です。PDF でも OCR 未処理のものや、暗号化された PDF は受け付けられないことがあります。一度 PDF を減色・再保存してからアップロードすると通ることが多いです。
Claude Code の場合、ローカルファイルは Read ツールで直接読むので、Web のアップロード機能は使いません。Web で試したファイルが通らない場合は、該当ファイルをローカルに保存して Claude Code 経由で扱うのが確実です。
5. MCP サーバーと Hook の失敗
症状: MCP サーバーが connection refused で起動しない
MCP サーバーは Claude Code 起動時にサブプロセスとして立ち上がります。起動ログは ~/.claude/logs/mcp-<server-name>.log に出力されます。接続拒否の場合、サーバーのバイナリが PATH に存在しない、実行権限がない、依存ライブラリが足りない、のいずれかが大半です。
対処は、claude mcp list で登録されている MCP サーバーの状態を確認し、失敗しているサーバーのログを cat ~/.claude/logs/mcp-<name>.log で読みます。bind: address already in use なら、前回のプロセスが残っているので pkill -f mcp-<name> で掃除してから再起動します。
症状: Hook が登録されているのに発火しない
~/.claude/settings.json に PostToolUse や PreToolUse の Hook を書いたのに動かない場合、最初に確認するのは JSON の構文エラーです。JSON として不正な状態だと Hook 全体が無視されます。jq . ~/.claude/settings.json で検証してください。
次に、Hook のパターンマッチングが正しいかを確認します。matcher にツール名を書く場合は完全一致で、大文字小文字も区別されます。Bash は効くが bash は効きません。
発火しているはずだが動作が見えない場合は、Hook のコマンドに echo "hook fired" >> /tmp/hook.log を仕込んで、実際に発火しているかを確認します。発火しているなら Hook 内のコマンドが失敗しているので、終了コードを確認してください。
症状: Hook が発火するが、その後 Claude が止まる
Hook のスクリプトが標準入力を待つような実装になっていると、Claude Code 全体が止まります。Hook は必ず非対話で即座に終了する設計にしてください。長い処理を走らせる必要がある場合は、nohup ... & でバックグラウンドに逃がし、Hook 本体は数ミリ秒で戻るようにします。
6. 環境変数・設定ファイルに起因する複合エラー
最後に、複数の層にまたがって症状が出る、環境変数由来の問題です。これは原因が見えにくく、最も時間を取られがちな領域です。
症状: CLAUDE_CODE_USE_POWERSHELL_TOOL=1 を設定してもプレビューツールが有効にならない
Windows 環境で PowerShell ツールをプレビュー有効化する環境変数ですが、シェルの種類によって設定方法が異なります。cmd.exe では set CLAUDE_CODE_USE_POWERSHELL_TOOL=1、PowerShell では $env:CLAUDE_CODE_USE_POWERSHELL_TOOL=1、WSL では export CLAUDE_CODE_USE_POWERSHELL_TOOL=1 です。
よくある落とし穴は、シェルのプロファイル（$PROFILE や .bashrc）に設定を書いたが、Claude Code 起動時のシェルが別で読み込まれていないケースです。claude --debug で起動時の環境変数ダンプを確認できるので、実際に CLAUDE_CODE_USE_POWERSHELL_TOOL が入っているかを見てください。
症状: CLAUDE.md の記述が無視される
プロジェクトの CLAUDE.md は、リポジトリルートに配置する必要があります。サブディレクトリに置いても読み込まれません。また、ユーザー単位の CLAUDE.md は ~/.claude/CLAUDE.md に置きます。両方を同時に使うことも可能で、プロジェクト側の記述がユーザー側より優先されます。
発火しているはずなのに効いていない場合は、内容が長すぎてコンテキストに収まっていない可能性を疑います。CLAUDE.md が 5,000 行を超えているような場合は、本当に必要な指示だけに絞り、残りは参照ドキュメントとして別ファイル化してください。
症状: claude --bare で起動すると期待した動作にならない
--bare フラグは CLAUDE.md・MCP サーバー・Hook の全てを無効化したクリーンな状態で起動します。普段の動作と明らかに違うときに切り分け用として使いますが、実務ではこのモードで通常作業するものではありません。どの設定が悪さをしているかを探すためのデバッグ用だと覚えておいてください。
根本原因に辿り着くための作業ルール
ここまでのパターンを振り返ると、どの層で起きているかを特定できれば、対処自体は大半が定型化できます。最後に、症状に惑わされず根本原因に辿り着くための実務的なルールを 3 つ共有します。
ひとつ目は、最初にログファイルを開く癖 をつけることです。~/.claude/logs/ 以下には起動ログ・MCP ログ・エラーログが出ており、症状だけ見て推測するより、ログを 10 秒見た方が早いことがほとんどです。
ふたつ目は、エラーメッセージの「どこで起きたか」を意識する ことです。同じ文言でも、CLI の起動時か、ツール呼び出し中か、応答生成中かで原因が全く違います。タイムスタンプと直前の操作を紐付けて記録するだけで、切り分けの速度が倍になります。
みっつ目は、再現手順を最小化する ことです。「なんとなく動かない」を「この 3 コマンドを実行すると必ず落ちる」に削ぎ落とせれば、原因は自然と見えてきます。Claude Code のエラーは運ではなく、入力に対する確定的な応答なので、最小再現があれば必ず追い詰められます。
次に同じ症状に遭ったときは、このハンドブックを開いて症状から該当章へ飛んでください。復旧までの時間が、確実に短くなるはずです。