⟐ Claude Code/2026-04-24上級

Claude Code エラー完全対処辞典 — 認証・決済・応答停止・ツール失敗を症状から逆引きする

Claude Code で実際に遭遇する 40 超のエラーパターンを、症状 → 原因 → 復旧手順の順で整理した実務向けハンドブックです。認証・決済・応答停止・ツール失敗・MCP・Hook まで、根本原因まで追える資料として活用いただけます。

claude-code¹²⁹ troubleshooting⁶¹ error¹⁵ handbook authentication³ billing⁶ mcp¹⁸ hooks¹⁴

✦ プレミアム記事

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 経由の場合は時刻ずれで無効になることがあり、スマートフォンの時刻を自動同期に設定し直してください。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦症状 → 原因 → 復旧手順の 3 ステップで引ける、Claude Code 全主要エラーの網羅マップ

✦カードが拒否される、決済が通らない、アカウント権限が下りないときの順序立てた切り分け手順

✦ツール失敗・Hook 失敗・MCP 接続不良で詰まったときに、どのログのどこを見るかが一目で分かる参照資料

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

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 の全てを無効化したクリーンな状態で起動します。普段の動作と明らかに違うときに切り分け用として使いますが、実務ではこのモードで通常作業するものではありません。どの設定が悪さをしているかを探すためのデバッグ用だと覚えておいてください。