Workers VPC でよく発生するエラーをトラブルシュートし、デバッグします。
Workers VPC がプライベートサービスへの接続を確立できない場合、fetch() は何が失敗したかを示すエラーコード付きの例外をスローします。これらのエラーコードは、Cloudflare ダッシュボードの VPC Service の Metrics タブでも確認できます。
エラーは、想定される原因に基づいて 3 つのカテゴリに分類されます。これらのカテゴリは、ダッシュボードの VPC Service の Metrics タブに表示されるラベルと一致します。
- Bad Upstream — トンネルまたはプライベートサービスに到達できません。トンネルのヘルス、サービスの可用性、ネットワーク / TLS 設定を確認します。
- Client — VPC Service の設定または Worker のコードが失敗の原因です。ターゲットのホスト名と Worker のリクエスト動作を確認します。
- Internal — Cloudflare インフラの問題です。継続する場合は Cloudflare サポートに連絡してください。
これらのエラーは、Cloudflare がプライベートサービスへの到達を試みたが接続に失敗したことを示します。トンネルが停止している、サービスが待ち受けていない、または Cloudflare とオリジンのあいだにネットワーク / TLS の問題がある可能性があります。
| エラーコード | 説明 | 推奨する対処 |
|---|---|---|
connection_refused |
プライベートサービスが TCP 接続を拒否しました。 | サービスが稼働し、想定ポートで待ち受けていることを確認します。ファイアウォールルールも確認します。 |
connection_terminated |
応答を受け取る前に、サービス側で接続が閉じられました。 | クラッシュやリソース枯渇がないか、サービスのログを確認します。 |
connection_timeout |
サービスへの接続試行がタイムアウトしました。 | トンネルからサービスに到達できることを確認します。トラフィックを遮断するネットワークレイテンシやファイアウォールルールがないか確認します。 |
connection_limit_reached |
サービスへの同時接続数が上限に達しました。 | より多くの接続を扱えるようサービスをスケールするか、Worker 側の同時接続数を減らします。 |
destination_unavailable |
サービスが利用不可と見なされています。 | トンネルが稼働し、サービスが健全であることを確認します。 |
destination_not_found |
このリクエストのルートを決定できませんでした。 | VPC Service の設定が有効なホストを指していること、トンネルがそのホストへトラフィックをルーティングするよう設定されていることを確認します。 |
destination_ip_prohibited |
宛先 IP アドレスが禁止されています。 | VPC Service に設定した IP アドレスが正しく、制限リストに含まれていないことを確認します。 |
destination_ip_unroutable |
宛先 IP へのネットワークルートがありません。 | IP アドレスが正しく、プライベートネットワーク内から到達できることを確認します。 |
proxy_loop_detected |
リクエストが同じプロキシに戻され、ループが発生します。 | VPC Service とトンネルの設定に循環ルーティングがないか確認します。 |
dns_error |
DNS 解決に失敗しました（例: SERVFAIL）。 | VPC Service に設定したホスト名が、プライベートネットワーク内から解決できることを確認します。DNS リゾルバーが正しく動作していることも確認します。よくある DNS 原因は トンネルエラー を参照してください。 |
dns_timeout |
DNS 解決がタイムアウトしました。 | DNS リゾルバーに到達でき、応答していることを確認します。VPC Service 設定でカスタム DNS リゾルバーの構成も検討します。 |
tls_protocol_error |
サービスへの接続時に TLS ハンドシェイクまたはプロトコルエラーが発生しました。 | サービスの TLS 設定を確認します。TLS バージョンと暗号スイートに互換性があることを確認します。 |
tls_certificate_error |
サービスの TLS 証明書の検証に失敗しました。 | サービスが 公的に信頼される CA または Cloudflare Origin CA 証明書 の有効な証明書を提示していることを確認します。 |
http_request_error |
HTTP リクエストエラーが発生しました。 | エラー応答の原因について、サービスのログを確認します。 |
http_upgrade_failed |
HTTP アップグレード（例: WebSocket）に失敗しました。 | サービスが要求されたプロトコルアップグレードに対応していることを確認します。 |
http_request_denied |
転送前にポリシーによってリクエストが拒否されました。 | サービスのアクセスポリシーと設定を確認します。 |
http_protocol_error |
サービスとの通信中に HTTP プロトコルエラーが発生しました。 | サービスが有効な HTTP で応答していることを確認します。 |
http_response_incomplete |
サービスが不完全な HTTP 応答を返しました。 | 応答の途中で接続を閉じる原因がないか、サービスを確認します。 |
これらのエラーは、プライベートサービス自体ではなく、VPC Service のセットアップまたは Worker の動作に問題があることを示します。
| エラーコード | 説明 | 推奨する対処 |
|---|---|---|
dns_error (NXDOMAIN) |
VPC Service に設定したホスト名が DNS に存在しません。 | VPC Service 設定のホスト名が正しく、そのホスト名の DNS レコードが存在することを確認します。 |
connection_read_timeout |
接続は確立されましたが、制限時間内にデータを受信できませんでした。 | 停滞または遅いリクエストがないか Worker のコードを確認します。Worker が応答を速やかに読み取っていることを確認します。 |
connection_write_timeout |
接続へデータを書き込めませんでした（バッファーがいっぱいです）。 | 応答データの消費が遅くないか、Worker のコードを確認します。 |
rate_limited |
このオリジンへの接続レート制限を超えました。 | このサービスへの Worker からの新規接続レートを下げます。 |
これらのエラーは、設定やオリジンサービスが原因ではない、Cloudflare インフラ内の問題を示します。
| エラーコード | 説明 | 推奨する対処 |
|---|---|---|
proxy_internal_error |
Cloudflare プロキシ内で内部エラーが発生しました。 | 設定が原因ではありません。このエラーが続く場合は Cloudflare サポート ↗ に連絡してください。 |
Workers VPC は、Cloudflare Tunnel 経由でプライベートサービスに接続するときに、ランタイムでエラーを返すことがあります。
| エラーメッセージ | 詳細 | 推奨する対処 |
|---|---|---|
Error: ProxyError: dns_error |
トンネル経由でプライベートサービスへ接続しようとしたとき、DNS 解決に失敗しました。 | このエラーは cloudflared のバージョンが古い場合に発生することがあります。cloudflared バージョン 2025.7.0 以降（最新版を推奨）を実行していることを確認します。Cloudflare Tunnel の更新手順 を参照してください。 |
Error: ProxyError: dns_error |
Cloudflare Tunnel が http2 プロトコル（TUNNEL_TRANSPORT_PROTOCOL:http2）で設定されている可能性があります。これは Cloudflare Zero Trust のトラフィックでは動作しますが (注を参照)、Workers VPC からの DNS 解決を妨げます。 |
Workers VPC では、Cloudflare Tunnel が QUIC トランスポートプロトコル で接続する必要があります。ファイアウォールでポート 7844 の送信 UDP トラフィックが許可されていることを確認します。 |
| リクエストが VPC 内に留まらない | 公開ホスト名を使った .fetch() の Worker リクエストが、VPC の外へ、VPC Service に設定したホスト名へルーティングされています。 |
Worker のコードと VPC Service では、バックエンドサービスに公開ホスト名ではなく、内部 VPC ホスト名を使ってください。 |
ダッシュボードまたは Wrangler で VPC Services と Tunnels の表示、作成、バインドができない場合は、ユーザーに必要なロールがあることを確認します。
Workers VPC は次のアカウントロールを使います。
- Workers VPC Services と Tunnels を表示するための
Connectivity Directory Read - Workers で VPC Services を一覧表示、読み取り、バインドするための
Connectivity Directory Bind - VPC Services の作成、更新、削除、および VPC Network バインディング経由でトンネルへ直接バインドするための
Connectivity Directory Admin
ロールの定義は ロール を参照してください。
ロールを最近更新したあとでもコマンドが失敗する場合は、Wrangler の認証を更新します。
npx wrangler logout
npx wrangler loginAPI トークン（CLOUDFLARE_API_TOKEN）で認証する場合は、トークンが必要なロールを持つユーザーに属していることを確認してください。