Skip to content

Commit 491e365

Browse files
thomasgauvin3 peopleauthored
docs: add Workers VPC connection error code reference (#28955)
* docs: add Workers VPC connection error code reference Add comprehensive error code reference to the Workers VPC troubleshooting page, organized by category (Service Unreachable, Configuration Error, Internal Error). Each error code includes a description and recommended fix. Restructure existing Tunnel errors into their own section. * docs: add Workers VPC metrics and settings dashboard changelog entry * Update src/content/docs/workers-vpc/reference/troubleshooting.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com> * Update src/content/docs/workers-vpc/reference/troubleshooting.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com> * [Workers VPC] Update error category names to match dashboard metrics labels * [Workers VPC] Update changelog date to March 18, remove settings image, add settings mention * Update src/content/changelog/workers-vpc/2026-03-18-metrics-and-settings-dashboard.mdx Co-authored-by: Caley Burton <caley@cloudflare.com> * [Workers VPC] Update changelog date to March 19 * [Workers VPC] Update changelog date to March 20 --------- Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com> Co-authored-by: Caley Burton <caley@cloudflare.com>
1 parent ace6612 commit 491e365

File tree

3 files changed

+77
-4
lines changed

3 files changed

+77
-4
lines changed

‎src/assets/images/changelog/workers-vpc/2026-03-20-metrics-dashboard.png‎

3.41 MB
Loading

‎src/content/changelog/workers-vpc/2026-03-20-metrics-and-settings-dashboard.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Observability for Workers VPC Services
3+
description: Debug and monitor your private network connections with per-service metrics, error breakdowns, and latency tracking.
4+
date: 2026-03-20
5+
---
6+
7+
Each VPC Service now has a **Metrics** tab so you can monitor connection health and debug failures without leaving the dashboard.
8+
9+
![Workers VPC Metrics dashboard showing connections, latency, and errors charts](~/assets/images/changelog/workers-vpc/2026-03-20-metrics-dashboard.png)
10+
11+
- **Connections** — See successful and failed connections over time, broken down by what is responsible: your origin (Bad Upstream), your configuration (Client), or Cloudflare (Internal).
12+
- **Latency** — Track connection and DNS resolution latency trends.
13+
- **Errors** — Drill into specific error codes grouped by category, with filters to isolate upstream, client, or internal failures.
14+
15+
You can also view and edit your VPC Service configuration, host details, and port assignments from the **Settings** tab.
16+
17+
For a full list of error codes and what they mean, refer to [Troubleshooting](/workers-vpc/reference/troubleshooting/).

‎src/content/docs/workers-vpc/reference/troubleshooting.mdx‎

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,72 @@ import { Render } from "~/components";
99

1010
Troubleshoot and debug errors commonly associated with Workers VPC.
1111

12-
## Connection errors
12+
## Connection error codes
1313

14-
Workers VPC may return errors at runtime when connecting to private services through Cloudflare Tunnel.
14+
When Workers VPC cannot establish a connection to your private service, `fetch()` will throw an exception with an error code describing what went wrong. These error codes are also visible in the **Metrics** tab of your VPC Service in the Cloudflare dashboard.
15+
16+
Errors are grouped into three categories based on the likely cause. These categories match the labels shown in the **Metrics** tab of your VPC Service in the dashboard.
17+
18+
- **Bad Upstream** — Your tunnel or private service is not reachable. Check tunnel health, service availability, and network/TLS configuration.
19+
- **Client** — Your VPC Service configuration or Worker code caused the failure. Check your target hostname and Worker request behavior.
20+
- **Internal** — A Cloudflare infrastructure issue. Contact Cloudflare support if this persists.
21+
22+
### Bad Upstream errors
23+
24+
These errors indicate that Cloudflare attempted to reach your private service but the connection failed. The tunnel may be down, the service may not be listening, or there is a network or TLS issue between Cloudflare and your origin.
25+
26+
| Error code | Description | Recommended fix |
27+
| --------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28+
| `connection_refused` | Your private service refused the TCP connection. | Verify your service is running and listening on the expected port. Check firewall rules. |
29+
| `connection_terminated` | The connection was closed by your service before a response was received. | Check your service logs for crashes or resource exhaustion. |
30+
| `connection_timeout` | The connection attempt to your service timed out. | Verify your service is reachable from the tunnel. Check for network latency or firewall rules blocking traffic. |
31+
| `connection_limit_reached` | The maximum number of concurrent connections to your service has been reached. | Scale your service to handle more connections, or reduce connection concurrency in your Worker. |
32+
| `destination_unavailable` | Your service is considered unavailable. | Verify your tunnel is running and your service is healthy. |
33+
| `destination_not_found` | No route could be determined for this request. | Check that your VPC Service configuration points to a valid host and that your tunnel is configured to route traffic to it. |
34+
| `destination_ip_prohibited` | The destination IP address is prohibited. | Verify the IP address configured for your VPC Service is correct and not on a restricted list. |
35+
| `destination_ip_unroutable` | No network route exists to the destination IP. | Check that the IP address is correct and reachable from within your private network. |
36+
| `proxy_loop_detected` | The request would be forwarded back to the same proxy, creating a loop. | Review your VPC Service and tunnel configuration for circular routing. |
37+
| `dns_error` | DNS resolution failed (for example, SERVFAIL). | Check that the hostname configured for your VPC Service is resolvable from within your private network. Verify your DNS resolver is working correctly. Refer to [Tunnel errors](#tunnel-errors) for common DNS causes. |
38+
| `dns_timeout` | DNS resolution timed out. | Check your DNS resolver is reachable and responding. Consider configuring a custom DNS resolver in your VPC Service settings. |
39+
| `tls_protocol_error` | A TLS handshake or protocol error occurred when connecting to your service. | Verify your service's TLS configuration. Ensure the TLS version and cipher suites are compatible. |
40+
| `tls_certificate_error` | Your service's TLS certificate failed verification. | Ensure your service presents a valid certificate from a [publicly trusted CA](/ssl/reference/certificate-authorities/) or a [Cloudflare Origin CA certificate](/ssl/origin-configuration/origin-ca/). |
41+
| `http_request_error` | An HTTP request error occurred. | Check your service logs for details on what caused the error response. |
42+
| `http_upgrade_failed` | An HTTP upgrade (for example, WebSocket) failed. | Verify your service supports the requested protocol upgrade. |
43+
| `http_request_denied` | The request was rejected by policy before being forwarded. | Review your service's access policies and configuration. |
44+
| `http_protocol_error` | An HTTP protocol error occurred when communicating with your service. | Check that your service is responding with valid HTTP. |
45+
| `http_response_incomplete` | Your service returned an incomplete HTTP response. | Check your service for issues that may cause it to close connections mid-response. |
46+
47+
### Client errors
48+
49+
These errors indicate a problem with your VPC Service setup or your Worker's behavior — not with the private service itself.
1550

16-
### Tunnel errors
51+
| Error code | Description | Recommended fix |
52+
| -------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
53+
| `dns_error` (NXDOMAIN) | The hostname configured for your VPC Service does not exist in DNS. | Verify the hostname in your VPC Service configuration is correct and that a DNS record exists for it. |
54+
| `connection_read_timeout` | The connection was established but no data was received within the time limit. | Check your Worker code for stalled or slow requests. Ensure your Worker is reading the response in a timely manner. |
55+
| `connection_write_timeout` | Data could not be written to the connection (buffers full). | Check your Worker code for slow consumption of response data. |
56+
| `rate_limited` | The connection rate limit to this origin has been exceeded. | Reduce the rate of new connections from your Worker to this service. |
57+
58+
:::note
59+
The `dns_error` code can appear as either a **Bad Upstream** error or a **Client** error depending on the DNS failure type. An NXDOMAIN response (hostname does not exist) is classified as a Client error because it typically means the VPC Service hostname is misconfigured. All other DNS failures (SERVFAIL, timeouts, and similar) are classified as Bad Upstream errors.
60+
:::
61+
62+
### Internal errors
63+
64+
These errors indicate an issue within Cloudflare's infrastructure that is not caused by your configuration or your origin service.
65+
66+
| Error code | Description | Recommended fix |
67+
| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
68+
| `proxy_internal_error` | An internal error occurred within the Cloudflare proxy. | This is not caused by your configuration. If this error persists, contact [Cloudflare support](https://support.cloudflare.com). |
69+
70+
## Tunnel errors
71+
72+
Workers VPC may return errors at runtime when connecting to private services through Cloudflare Tunnel.
1773

1874
| Error Message | Details | Recommended fixes |
1975
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2076
| `Error: ProxyError: dns_error` | DNS resolution failed when attempting to connect to your private service through the tunnel. | This error may occur if your `cloudflared` version is outdated. Ensure you are running `cloudflared` version 2025.7.0 or later (latest version recommended). See [Cloudflare Tunnel update instructions](/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/update-cloudflared/). |
21-
| `Error: ProxyError: dns_error` | Cloudflare Tunnel may be configured with `http2` protocol (`TUNNEL_TRANSPORT_PROTOCOL:http2`), which works for Cloudflare Zero Trust [(see note)](/workers-vpc/configuration/tunnel/#create-and-run-tunnel-cloudflared) traffic but prevents DNS resolution from Workers VPC. | Workers VPC requires Cloudflare Tunnel to connect using the [QUIC transport protocol](/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/run-parameters/#protocol). Ensure outbound UDP traffic on port 7844 is allowed through your firewall. |
77+
| `Error: ProxyError: dns_error` | Cloudflare Tunnel may be configured with `http2` protocol (`TUNNEL_TRANSPORT_PROTOCOL:http2`), which works for Cloudflare Zero Trust [(see note)](/workers-vpc/configuration/tunnel/#create-and-run-tunnel-cloudflared) traffic but prevents DNS resolution from Workers VPC. | Workers VPC requires Cloudflare Tunnel to connect using the [QUIC transport protocol](/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/run-parameters/#protocol). Ensure outbound UDP traffic on port 7844 is allowed through your firewall. |
2278
| Requests not staying within VPC | Worker requests using `.fetch()` with a public hostname are routing out of the VPC to the hostname configured for the VPC Service. | Ensure your Worker code and the VPC Service use the internal VPC hostname for backend services, not a public hostname. |
2379

2480
## Permission errors

0 commit comments

Comments
 (0)