Debugging Cloudflare Tunnel errors: from symptom to cause

When a tunnel fails, the error you see in the browser is only the last link in a chain of five or six. The visitor reaches Cloudflare, Cloudflare finds your tunnel, the tunnel connector is alive, the connector reaches your service, and your service answers. A break at any link produces a different symptom. If you can tell which link broke, the fix is usually one line.

This guide gives a method for narrowing it down, then a table of the errors you are most likely to meet.

Work from the outside in

Check each link in order, and stop at the first one that fails.

1. Does the hostname resolve to Cloudflare?

dig +short files.example.com

A proxied hostname returns Cloudflare addresses, not your own. If it returns nothing, the DNS record was never created, so run cloudflared tunnel route dns again. If it returns your server’s real address, the record is not proxied or points at the wrong place.

2. Is the tunnel connected?

cloudflared tunnel info homelab

This lists the connections your tunnel currently has. No connections means no connector is running, or none can reach Cloudflare.

3. What does the connector say?

sudo systemctl status cloudflared --no-pager
sudo journalctl -u cloudflared -n 100 --no-pager

Most problems announce themselves here, in plain language.

4. Does your service answer from the connector’s point of view?

This is the one people skip. From the machine running cloudflared, use the exact address from config.yml:

curl -v http://localhost:8080

If that fails, the tunnel is innocent. Your service is down, on a different port or not listening on that address.

5. Which rule matches?

cloudflared tunnel --config /etc/cloudflared/config.yml ingress rule https://files.example.com

It tells you which ingress rule the URL hits. A wildcard rule above the one you wanted is a frequent surprise.

Symptoms and causes

Symptom	Cause	Fix
Error 1033	Cloudflare cannot find a healthy connector for the tunnel. It is stopped, disconnected, or the hostname’s DNS points at a different tunnel	Start the service and read its logs. Confirm the CNAME points at the right tunnel
502 Bad Gateway (“Unable to reach the origin service”)	The tunnel is up, but cloudflared cannot reach your service. It is not running, the port is wrong, or the scheme is wrong, http:// against an HTTPS service or the reverse	Run the curl test from step 4. Fix the address or scheme in config.yml
failed to dial to edge with quic: timeout	Outbound UDP 7844 is blocked, so QUIC cannot connect	Allow outbound UDP 7844. cloudflared falls back to HTTP/2 over TCP, or you can force it with protocol: http2 in the config
dial tcp ... i/o timeout	Outbound TCP 7844 is blocked as well. If both are blocked, the tunnel cannot connect	Allow outbound TCP and UDP 7844 to Cloudflare
SRV lookup failure for _v2-origintunneld._tcp.argotunnel.com	The local resolver cannot return SRV records, or outbound DNS is blocked	Test with dig SRV _v2-origintunneld._tcp.argotunnel.com @1.1.1.1. If that works, switch the host to a resolver that does
ERR_TOO_MANY_REDIRECTS	Your service redirects HTTP to HTTPS, but the service URL says http://, so it redirects forever	Point the service at https:// and set the origin settings below
x509: certificate signed by unknown authority	Your HTTPS origin uses a certificate cloudflared does not trust, such as a self-signed or internal one	Trust the certificate authority, or set originServerName if the name differs. Use noTLSVerify only as a temporary measure
tls: handshake failure or an SSL error at the edge	The hostname is not covered by the edge certificate. Universal SSL does not cover multi-level subdomains such as a.b.example.com	Use a single-level hostname, or an advanced certificate
websocket: bad handshake	The tunnel is not running, WebSockets are off, the zone’s SSL/TLS mode is Off, a bot setting is blocking the request, or a Workers route is interfering	Work through those causes. Set SSL/TLS to Flexible, Full or Full (strict)
Tunnel credentials file ... doesn't exist	credentials-file in config.yml points at a path that is not there, or that the service user cannot read	Correct the path, and check ownership and permissions
cloudflared service is already installed	A machine can have only one cloudflared service	Add routes to the existing tunnel, or run sudo cloudflared service uninstall first
An A, AAAA, or CNAME record with that host already exists	An old DNS record is using the hostname	Delete it in the dashboard, or choose another hostname
failed to sufficiently increase receive buffer size	The kernel’s UDP buffer limit is low	Harmless in most cases. See the hardening guide if you want to raise it
socket: too many open files	The process has run out of file descriptors	Raise the limit with LimitNOFILE= in the unit

Two settings that fix most HTTPS origin trouble

If your service is an HTTPS site with a certificate for its internal name, tell cloudflared the name to expect:

ingress:
  - hostname: files.example.com
    service: https://nas.internal:5001
    originRequest:
      originServerName: nas.internal
  - service: http_status:404

If the certificate is self-signed and you cannot install the authority that signed it, you can disable the check for that one service:

    originRequest:
      noTLSVerify: true

Understand what that does before you use it. It stops cloudflared verifying that the thing answering on that address is who it claims to be. On a trusted LAN that is a small risk. On anything else, it is the wrong fix, and trusting the certificate authority is the right one.

Testing the connection to Cloudflare itself

If the tunnel will not connect at all, check the network path from the connector’s machine:

nc -vz -w 3 region1.v2.argotunnel.com 7844
dig SRV _v2-origintunneld._tcp.argotunnel.com @1.1.1.1

The first checks that outbound TCP 7844 gets through. The second checks that DNS can return the records cloudflared uses to find Cloudflare’s edge. Firewalls that inspect TLS, or that only allow ports 80 and 443 outbound, are the usual causes when these fail. Cloudflare’s documentation lists the current ports and address ranges to allow.

When the problem is Access, not the tunnel

If you get a Cloudflare login page you did not expect, or a login loop, or “you are not allowed”, the tunnel is working and the fault is in the Access policy. Check the application’s hostname, the policy’s rules and the identity you are signing in with. The Access guide covers each.

Sources: Cloudflare’s tunnel troubleshooting and configuration file documentation.