对通常与 Workers VPC 相关的错误进行故障排除和调试。
当 Workers VPC 无法建立与您的专用服务的连接时，fetch() 将抛出异常，其中包含描述出现什么问题的错误代码。这些错误代码在 Cloudflare 仪表板中您的 VPC Service 的 **Metrics（指标）**选项卡中也可见。
根据可能的原因，错误分为三类。这些类别与仪表板中 VPC Service 的 Metrics（指标） 选项卡中显示的标签相匹配。
- Bad Upstream（上游错误）— 您的隧道或专用服务无法访问。检查隧道运行状况、服务可用性和网络/TLS 配置。
- Client（客户端）— 您的 VPC Service 配置或 Worker 代码导致了失败。检查您的目标主机名和 Worker 请求行为。
- Internal（内部）— Cloudflare 基础设施问题。如果此问题持续存在，请联系 Cloudflare 支持。
这些错误表明 Cloudflare 尝试访问您的专用服务但连接失败。隧道可能已关闭，服务可能未在侦听，或者 Cloudflare 与您的源站之间存在网络或 TLS 问题。
| Error code（错误代码） | Description（描述） | Recommended fix（建议修复） |
|---|---|---|
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 原始 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 的行为存在问题，而不是专用服务本身存在问题。
| Error code（错误代码） | Description（描述） | Recommended fix（建议修复） |
|---|---|---|
dns_error (NXDOMAIN) |
在 DNS 中不存在为您的 VPC Service 配置的主机名。 | 验证 VPC Service 配置中的主机名是否正确并且存在相应的 DNS 记录。 |
connection_read_timeout |
已建立连接，但在时间限制内未收到任何数据。 | 检查 Worker 代码中是否有停滞或缓慢的请求。确保您的 Worker 及时读取响应。 |
connection_write_timeout |
无法将数据写入连接（缓冲区已满）。 | 检查您的 Worker 代码是否存在缓慢消耗响应数据的情况。 |
rate_limited |
超过了到此源站的连接速率限制。 | 降低从您的 Worker 到该服务的新连接速率。 |
这些错误表明 Cloudflare 基础设施内存在问题，该问题并非由您的配置或源站服务引起。
| Error code（错误代码） | Description（描述） | Recommended fix（建议修复） |
|---|---|---|
proxy_internal_error |
Cloudflare 代理中发生内部错误。 | 这不是由您的配置引起的。如果此错误持续存在，请联系 Cloudflare 支持 ↗。 |
通过 Cloudflare Tunnel 连接到专用服务时，Workers VPC 可能会在运行时返回错误。
| Error Message（错误消息） | Details（详细信息） | Recommended fixes（建议修复） |
|---|---|---|
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 内 | Worker 请求使用 .fetch() 和公共主机名，正路由出 VPC，指向为 VPC Service 配置的主机名。 |
确保您的 Worker 代码和 VPC Service 将内部 VPC 主机名用于后端服务，而不是公共主机名。 |
如果您无法在仪表板中或通过 Wrangler 查看、创建或绑定 VPC Services 和 Tunnels，请确保您的用户具有所需的角色。
Workers VPC 使用以下账户角色：
Connectivity Directory Read：查看 Workers VPC 服务和隧道。Connectivity Directory Bind：列出、读取并在 Workers 中绑定（binding）VPC 服务。Connectivity Directory Admin：创建、更新和删除 VPC 服务，并通过 VPC 网络绑定（binding）直接绑定到隧道。
有关角色定义，请参阅角色。
如果您的角色最近已更新，但命令仍然失败，请刷新 Wrangler 身份验证：
npx wrangler logout
npx wrangler login如果您使用 API 令牌（CLOUDFLARE_API_TOKEN）进行身份验证，请确保该令牌属于具有所需角色的用户。