Troubleshoot and debug

Troubleshoot and debug errors commonly associated with Workers VPC.

Connection error codes

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.

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.

• Bad Upstream — Your tunnel or private service is not reachable. Check tunnel health, service availability, and network/TLS configuration.
• Client — Your VPC Service configuration or Worker code caused the failure. Check your target hostname and Worker request behavior.
• Internal — A Cloudflare infrastructure issue. Contact Cloudflare support if this persists.

Bad Upstream errors

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.

Error code	Description	Recommended fix
connection_refused	Your private service refused the TCP connection.	Verify your service is running and listening on the expected port. Check firewall rules.
connection_terminated	The connection was closed by your service before a response was received.	Check your service logs for crashes or resource exhaustion.
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.
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.
destination_unavailable	Your service is considered unavailable.	Verify your tunnel is running and your service is healthy.
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.
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.
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.
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.
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 for common DNS causes.
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.
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.
tls_certificate_error	Your service's TLS certificate failed verification.	Ensure your service presents a valid certificate from a publicly trusted CA or a Cloudflare Origin CA certificate.
http_request_error	An HTTP request error occurred.	Check your service logs for details on what caused the error response.
http_upgrade_failed	An HTTP upgrade (for example, WebSocket) failed.	Verify your service supports the requested protocol upgrade.
http_request_denied	The request was rejected by policy before being forwarded.	Review your service's access policies and configuration.
http_protocol_error	An HTTP protocol error occurred when communicating with your service.	Check that your service is responding with valid HTTP.
http_response_incomplete	Your service returned an incomplete HTTP response.	Check your service for issues that may cause it to close connections mid-response.

Client errors

These errors indicate a problem with your VPC Service setup or your Worker's behavior — not with the private service itself.

Error code	Description	Recommended fix
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.
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.
connection_write_timeout	Data could not be written to the connection (buffers full).	Check your Worker code for slow consumption of response data.
rate_limited	The connection rate limit to this origin has been exceeded.	Reduce the rate of new connections from your Worker to this service.

Note

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.

Internal errors

These errors indicate an issue within Cloudflare's infrastructure that is not caused by your configuration or your origin service.

Error code	Description	Recommended fix
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 ↗.

Tunnel errors

Workers VPC may return errors at runtime when connecting to private services through Cloudflare Tunnel.

Error Message	Details	Recommended fixes
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.
Error: ProxyError: dns_error	Cloudflare Tunnel may be configured with http2 protocol (TUNNEL_TRANSPORT_PROTOCOL:http2), which works for Cloudflare Zero Trust (see note) traffic but prevents DNS resolution from Workers VPC.	Workers VPC requires Cloudflare Tunnel to connect using the QUIC transport protocol. Ensure outbound UDP traffic on port 7844 is allowed through your firewall.
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.

Permission errors

If you cannot view, create, or bind VPC Services and Tunnels in the dashboard or via Wrangler, ensure your user has the required roles.

Workers VPC uses the following account roles:

• Connectivity Directory Read to view Workers VPC Services and Tunnels.
• Connectivity Directory Bind to list/read services and bind them in Workers.
• Connectivity Directory Admin to create, update, and delete services.

For role definitions, refer to Roles.

If your roles were recently updated and commands are still failing, refresh Wrangler authentication:

npx wrangler logout
npx wrangler login

If you authenticate with an API token (CLOUDFLARE_API_TOKEN), ensure the token belongs to a user with the required roles.