Cloudflare Tunnel troubleshooting guide — fact-check and revision log

Published July 10, 2026 · Last verified against cloudflared 2026.5.2 on Linux

This page documents how the Cloudflare Tunnel troubleshooting guide was drafted and reviewed. The guide itself is at /guides/cloudflare-tunnel-troubleshooting/.

Sources used

Official documentation

• Cloudflare Tunnel troubleshooting — developers.cloudflare.com/.../troubleshoot-tunnels/
• Cloudflare Tunnel local management — developers.cloudflare.com/.../local-management/
• Cloudflare Tunnel get started — developers.cloudflare.com/.../get-started/

Source repository

• cloudflared GitHub repo — github.com/cloudflare/cloudflared

Live CLI checks

• cloudflared --version reported 2026.5.2 (built 2026-05-27-10:38 UTC) on Linux.
• cloudflared tunnel --help confirmed the named-tunnel command family and its documented behavior.
• cloudflared tunnel route dns --help confirmed that the subcommand creates a DNS CNAME record pointing a hostname to a tunnel.
• cloudflared tunnel run --help confirmed the credential and UUID behavior used in this guide.

Claim audit

Verified against the official troubleshooting docs

• Named tunnels can fail at the local origin, the running connector, the tunnel identity, the DNS route, or a policy layer. ✓ Confirmed in the troubleshoot-tunnels page's "common errors" table.
• cloudflared tunnel info <NAME> reports connector health, version, and last-seen time. ✓ Confirmed against --help output.
• cloudflared tunnel diag creates a diagnostic archive from a local instance. ✓ Confirmed against --help output.
• cloudflared tunnel cleanup removes old connection records. ✓ Confirmed against --help output.

Claims that remain conditional by design

• The exact phrasing of --no-tls-verify was verified against the help output but the surrounding warning text can change between releases.
• The diagnostic-archive contents evolve with the daemon; treat it as evidence of state, not as a stable schema.
• Cloudflare Access behavior (the "policy or application behavior" layer) is intentionally not exhaustive — the guide links to the Access docs for the current contract.

Revisions applied during review

1. Connector wording was softened to match tunnel info --help — the original draft said "shows active connectors" but the CLI says "details about active connectors." Both are technically correct, but the softer phrasing matches the official contract.
2. The DNS decision-tree branch now tells the reader what to compare before changing DNS (record the exact dig result, confirm the hostname and intended tunnel) — this prevents the common "overwrite DNS to fix a non-DNS problem" mistake.
3. The escalation checklist is a real checklist (8 items with empty checkboxes) instead of a paragraph of suggestions.
4. Added explicit "What not to do" section covering: --no-tls-verify as a generic fix, exposing the origin publicly for faster testing, pasting credentials, enabling debug logging by default, and changing Access policies on a public anomaly.
5. Removed the first two MiniMax M3 runs that returned unified-diff/tool transcripts instead of articles. The remaining clean draft went through the editorial review pass documented above.

Last verified

July 10, 2026 against cloudflared 2026.5.2 on Linux and the official URLs above. Re-run cloudflared --version and compare the current official documentation before following a command after an upgrade. If the version you are running differs from the one listed here, include that difference in any escalation.