無料相談する

カテゴリー / エラー・不具合の対処

Claude Codeのネットワークエラー対処｜エラー別の原因と直し方

NO WAVE公開 更新 読了目安 14分

この記事の目次

Claude Codeのネットワークエラーは、公式のエラーリファレンスによれば、多くが手元のネットワーク・プロキシ・ファイアウォールで起きている。エラー文を手掛かりに切り分けられる。通信経路そのものが失敗する系（Connection refused、ENOTFOUND など）なら、まず同じシェルで curl -I https://api.anthropic.com を実行して経路を確かめ、社内プロキシ配下なら HTTPS_PROXY を起動前に設定する。証明書系（UNABLE_TO_GET_ISSUER_CERT_LOCALLY、SELF_SIGNED_CERT_IN_CHAIN）なら、社内CAのバンドルを NODE_EXTRA_CA_CERTS で指定する。この記事では、エラー文ごとの原因と、設定反映の状態を実際に確かめる方法までを順に示す。

そのエラーは本当にネットワークエラーか?

最初に、サーバー側の障害やレート制限と区別しておく。公式の分類では次のように分かれる。

表示 意味 手元の通信設定を触るべきか
API Error: 500 などの5xx API内部の障害。プロンプト・設定・アカウントが原因ではない 触らない。status.claude.com を確認して待つ
API Error: Repeated 529 Overloaded errors API全体が一時的に容量不足。利用上限には数えられない 触らない。時間を置くか /model で別モデルへ
API Error: Request rejected (429) APIキーやクラウド側プロジェクトに設定されたレート制限 触らない。レート制限の解説へ
Unable to connect to API、SSL certificate、Socket is closed など 経路上の問題 触る。この記事の対象

注意したいのは API Error: 502 Bad Gateway のような表示だ。公式によれば、プロキシやロードバランサーがHTMLのエラーページで応答した場合、そのページのタイトルがそのまま表示される。5xxに見えても、社内のプロキシが返しているなら手元側の問題になる。

Claude Codeは一時的な失敗を最大10回まで指数バックオフで自動リトライしてからエラーを出すので、表示された時点で続いている問題と考えてよい。エラー全体の分類はClaude Codeのエラーを原因別に切り分ける方法にまとめている。

「Unable to connect to API」系のエラー文は何を示しているか?

TCP接続が失敗したか、完了しなかったことを示す。コード付きの表示では、括弧内のエラーコードで種類を確認できる。

表示の要点 コード 公式が示す方向
Connection refused ConnectionRefused / ECONNREFUSED ファイアウォールかプロキシが遮断している可能性
Can’t reach the API server ENOTFOUND インターネット接続かDNSを確認
No internet route EHOSTUNREACH 接続かVPNを確認
Couldn’t connect through your proxy ERR_PROXY_TUNNEL プロキシがトンネルを拒否。資格情報と、このホストへの許可を確認
Connection dropped ECONNRESET 接続が途中で切断
Request timed out なし インターネット接続とプロキシ設定を確認

v2.1.227より前は Unable to connect to API (ECONNREFUSED) の書式なので、括弧内のコードで表を引く。典型的な原因は、インターネットに出られない、VPNが api.anthropic.com を遮断している、必要な社内プロキシが未設定、の3つだ。

最初に実行する切り分けの手順は?

Claude Codeを起動しているのと同じシェルで、APIのホストに届くかを確かめる。

curl -I https://api.anthropic.com

Windows PowerShellでは、curl が Invoke-WebRequest の別名になっているため curl.exe を明示する。

curl.exe -I https://api.anthropic.com

届かなければ、接続確認でネットワーク自体かプロキシ・ファイアウォールの問題に絞れる。

一方、curlは通るのにClaude Codeだけ失敗する場合は、公式によれば原因は通常、ネットワークそのものではなくランタイムとネットワークの間にある。確認する場所は次のとおり。

  • ANTHROPIC_BASE_URL の残り: echo $ANTHROPIC_BASE_URL（PowerShellでは echo $env:ANTHROPIC_BASE_URL）で確認し、settings.json の env ブロックも見る。設定されていると、Claude Codeは api.anthropic.com ではなくその宛先へ送る。以前使っていたローカルのプロキシやゲートウェイを指したまま残っていると、curlは通るのに Connection refused になる。削除したら新しいターミナルから起動し直す
  • Linux・WSLのDNS: /etc/resolv.conf に到達できないネームサーバーが書かれていないか確認する。WSLはホスト側から壊れたリゾルバ設定を引き継ぐことがある
  • macOSの残ったVPN: 切断・削除したVPNクライアントがトンネルやルーティングを残すことがある。ifconfig で古い utun インターフェースが残っていないか確認し、システム設定でVPNのネットワーク拡張を削除する
  • Docker Desktopなど: コンテナランタイムが外向きの通信を横取りすることがある。一度終了して再試行すれば切り分けられる

初回セットアップ中に Unable to connect to Anthropic services と出て終了した場合も同じ手順でよい。このチェックは api.anthropic.com と platform.claude.com に各10秒で到達確認を行い、プロキシ経由で失敗したときはメッセージに HTTPS_PROXY などの変数名が出る。その変数の値が正しいプロキシを指しているかを確認する。回線に制限がないのに失敗が続く場合は、利用地域がClaude Codeの提供対象外の可能性もある。

会社のプロキシ配下ではどう設定するか?

Claude Codeは標準のプロキシ環境変数に対応している。公式の設定例は次のとおり。

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

設定で押さえる点は4つある。

  1. 起動前に設定する。シェルの環境変数は起動時に一度だけ読まれるので、起動中のセッションには後から反映されない
  2. SOCKSプロキシには対応していない
  3. Basic認証のプロキシは、プロキシURLの中に資格情報を含める形で指定する（公式は、スクリプトにパスワードを直書きしないよう注意している）。NTLMやKerberosなどの認証方式が必要なプロキシは、公式はその方式に対応したLLMゲートウェイの利用を検討するよう案内している
  4. URLの書式。起動時に検証される設定はプロキシURLだけで、http:// が抜けているなど解釈できない値だと、変数名を示すエラーで起動が止まる

プロキシのURLが分からなければ、IT部門に確認するかブラウザのプロキシ設定を見る。インストール段階で失敗しているなら、HTTPS_PROXY と HTTP_PROXY を設定してからインストーラを実行する（手順はインストールの解説）。

証明書エラー（SSL）はどう直すか?

ネットワーク上のプロキシやセキュリティ機器が独自の証明書でTLS通信を検査しており、Claude Codeの証明書検証で信頼されていない状態だ。表示は次のコードを含む。

  • SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)
  • Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN)

v2.1.199以降、証明書の検証失敗はリトライされず、最初の試行で表示される。

直し方は、組織のCA証明書バンドルを用意して指定することだ。

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

ここで知っておきたいのは、Claude Codeが既定で、同梱のMozilla CA証明書とOSの証明書ストアの両方を信頼する点だ（CLAUDE_CODE_CERT_STORE の既定値は bundled,system）。TLS検査プロキシのルート証明書がOSの信頼ストアに入っていれば、追加設定なしで動く。ただしOSストアを読むには tls.getCACertificates を備えたランタイムが必要で、ネイティブインストーラ版は常に備え、npm版はNode 22.15以降が必要になる。それより古いNodeでは、同梱の証明書と NODE_EXTRA_CA_CERTS だけが適用される。

公式が明確に禁じているのが NODE_TLS_REJECT_UNAUTHORIZED=0 の設定で、証明書の検証そのものを無効にしてしまう。エラーを消す目的で使わない。CA証明書のファイルが手元にない場合はIT部門に依頼する。プロキシが原因かを確かめたいときは、プロキシを通らない直接の回線で試すと切り分けられる。

応答の途中で止まる・切れるのはなぜか?

ネットワークエラーのうちストリーミング中の通信が切れる系統で、エラー文によって原因が違う。

表示 公式が示す原因 対処
Socket is closed 応答の受信中に接続が閉じた。最も多いのはWindowsの社内プロキシが確立済みのトンネルを途中で切るケース claude update でv2.1.214以降にして再送信。続くならプロキシ設定を確認
API returned an empty or malformed response 通常は、プロキシ・ゲートウェイ・ネットワークのサインインページがAPIの代わりに応答した ゲストWi-Fiなどはブラウザでサインインを済ませて再試行
Streaming response ended before any complete data was received 通常は、プロキシやゲートウェイがストリーミング応答の本文を消費・変換している ストリーミングの本文とヘッダーを無加工で通すよう中継装置を設定

2行目のエラーには Response: という説明が付き、HTML本文だった、Anthropicのリクエストidがない、nginx や cloudflare などのサーバー名がある、といった情報が出る。これらは途中の何かがAPIの代わりに返事をした印で、IT部門への相談材料になる。

エラーではなく、スピナーに Waiting for API response · will retry in … · check your network と出る場合もある。これは20秒データが届かないときの表示で、まだ失敗ではない。毎回出るならネットワークの問題として扱う。遅い回線やプロキシでタイムアウトが頻発する場合は、リクエストごとのタイムアウト API_TIMEOUT_MS（既定600000ミリ秒）を引き上げられる。通信に問題がない状態での遅さや停止は、応答が遅いときの対処と途中で止まるときの対処で扱っている。

ファイアウォールでは何を許可してもらえばよいか?

公式のネットワーク要件では、プロキシとファイアウォールで許可すべき接続先が示されており、コンテナや制限されたネットワーク環境では特に必要とされている。このうちClaude APIとログインに使うのは次の3つだ。

接続先 用途
api.anthropic.com Claude APIへのリクエスト
claude.ai claude.aiアカウントの認証
platform.claude.com Anthropic Consoleアカウントの認証。claude.aiアカウントでもトークンの交換・更新がここに向かうため、どちらのログインでも必要

加えて、ネイティブインストーラと自動更新は downloads.claude.ai、npmやbunでのインストールは registry.npmjs.org を使う。プラグインやnpxで起動するMCPサーバーも registry.npmjs.org、Claude in Chrome連携は bridge.claudeusercontent.com を使うなど、用途ごとの接続先が表にまとまっているので、IT部門には公式のEnterprise network configurationにある「Network access requirements」の表をそのまま渡すと話が早い。

Amazon Bedrockなどのクラウド経由で使う場合、モデルの通信と認証は api.anthropic.com ではなくそのプロバイダへ向かう。構成についてはClaude CodeとAmazon Bedrockの連携を参照してほしい。

設定が効いているかはどう確かめるか?

公式によれば、プロキシのアドレス違いや証明書のパス違いは、多くの設定が読み込み時に検証されないため、通常は後のリクエストの接続エラーや証明書エラーで分かる。リクエストを送る前に確かめるには2つの方法がある。

1つ目はデバッグログ付きでの起動だ。

claude --debug

ログは ~/.claude/debug/<session-id>.txt に書き出される。NODE_EXTRA_CA_CERTS が読み込まれていれば CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS という行があり、読めなかった場合は Failed to read か Failed to load の行に理由が出る。

2つ目は対話セッション内での /status だ。Proxy の行に有効なプロキシURLが表示され、解釈できない値は無効として扱われたことが示される。Additional CA cert(s) の行は NODE_EXTRA_CA_CERTS のパスを表示するだけで、ファイルが読めたかは確認しないため、こちらはデバッグログで確かめる。

もう一点、claude agents、--bg、/background で動くバックグラウンドエージェントを使う場合、シェルで export しただけのプロキシやCAの設定は届かないことがある。公式は、同じ変数を ~/.claude/settings.json の env ブロックに書くよう案内している。settings.json の書き方はsettings.jsonの解説を参照してほしい。

表示が記事と違うときは?

WSL2・SSH・コンテナでログインだけ失敗する場合は、通信ではなくログインのリダイレクトの問題のことが多い。ログインできない時の切り分け方を参照してほしい。

ここで挙げたエラー文や表示の書式は、バージョンによって変わることがある（本文中のv2.1.xxxの注記はその例）。手元の表示が一致しない場合は、claude update で更新したうえで、公式のError referenceにある「Network and connection errors」を確認してほしい。

こうした切り分けを、MCPやhooks、権限設定の詰まりにも自分で応用できるようになりたい人向けに、月額1,980円から参加できる学習コミュニティ「AI駆動ラボ」(lab.no-wave.jp)を用意している。

CONTINUE THE SESSION

関連記事