{"record":{"id":"744862760fc583d7","repo":"cloudflare/cloudflared","slug":"error-running-tunnel","errorCode":null,"errorMessage":"error running tunnel","messagePattern":"error running tunnel","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/tunnel/cmd.go","lineNumber":299,"sourceCode":"\t\t// pass empty string as secret to generate one\n\t\ttunnel, err = sc.create(name, credentialsOutputPath, \"\")\n\t\tif err != nil {\n\t\t\treturn errors.Wrap(err, \"failed to create tunnel\")\n\t\t}\n\t} else {\n\t\tsc.log.Info().Str(LogFieldTunnelID, tunnel.ID.String()).Msg(\"Reusing existing tunnel with this name\")\n\t}\n\n\tif r, ok := routeFromFlag(sc.c); ok {\n\t\tif res, err := sc.route(tunnel.ID, r); err != nil {\n\t\t\tsc.log.Err(err).Str(\"route\", r.String()).Msg(routeFailMsg)\n\t\t} else {\n\t\t\tsc.log.Info().Msg(res.SuccessSummary())\n\t\t}\n\t}\n\n\tif err := sc.run(tunnel.ID); err != nil {\n\t\treturn errors.Wrap(err, \"error running tunnel\")\n\t}\n\n\treturn nil\n}\n\nfunc routeFromFlag(c *cli.Context) (route cfapi.HostnameRoute, ok bool) {\n\tif hostname := c.String(\"hostname\"); hostname != \"\" {\n\t\tif lbPool := c.String(cfdflags.LBPool); lbPool != \"\" {\n\t\t\treturn cfapi.NewLBRoute(hostname, lbPool), true\n\t\t}\n\t\treturn cfapi.NewDNSRoute(hostname, c.Bool(overwriteDNSFlagName)), true\n\t}\n\treturn nil, false\n}\n\nfunc StartServer(\n\tc *cli.Context,\n\tinfo *cliutil.BuildInfo,","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/cmd.go#L281-L317","documentation":"After creating or reusing the tunnel and applying any --route, runAdhocNamedTunnel starts the tunnel with sc.run(tunnel.ID); any failure there (connecting to Cloudflare edge, serving the origin, credential/protocol problems) is wrapped as 'error running tunnel'. It signals the tunnel process exited with an error rather than being a creation-time problem.","triggerScenarios":"`cloudflared tunnel run --name <name>` where sc.run(tunnel.ID) returns an error: cannot reach Cloudflare edge (network/firewall blocking QUIC 7844/UDP or HTTPS 443), invalid or unreadable credentials file, hostname not routed, origin unreachable causing serve failure, or context canceled with an error exit.","commonSituations":"Corporate firewalls blocking UDP/QUIC (fix: --protocol http2); credentials file moved or deleted; ICMP/egress restrictions; bad local origin URL in config so the proxy fails immediately; running in an environment without outbound 443.","solutions":["Read the wrapped inner error — it names the actual failing stage (edge connection, credentials, origin).","Try --protocol http2 if QUIC/UDP is blocked by the network.","Re-run `cloudflared tunnel login` or re-create the tunnel if the credentials file is missing/corrupt.","Verify the origin service URL in your config is reachable (`curl` it locally).","Ensure outbound TCP 443 (and UDP 7844 for QUIC) to Cloudflare edge is allowed."],"exampleFix":"// before\ncloudflared tunnel run --name mytunnel   # QUIC blocked by firewall\n\n// after\ncloudflared tunnel run --name mytunnel --protocol http2","handlingStrategy":"retry","validationCode":"# preflight\nnc -z -w3 region1.v2.argotunnel.com 443 || echo \"edge TCP 443 blocked\"\n# and ensure the credentials file exists:\ntest -f ~/.cloudflared/<TUNNEL-ID>.json || echo \"credentials missing\"","typeGuard":null,"tryCatchPattern":"for attempt := 0; attempt < 3; attempt++ {\n    err := runTunnelCmd()\n    if err == nil { break }\n    if strings.Contains(err.Error(), \"error running tunnel\") && isTransient(err) {\n        time.Sleep(backoff(attempt)); continue\n    }\n    log.Fatal(err)\n}","preventionTips":["Allow egress on TCP 443 and UDP 7844 to Cloudflare edge; fall back to --protocol http2 when UDP is blocked","Keep the tunnel credentials JSON alongside cert.pem and don't move it","Verify origin services are listening before starting the tunnel","Supervise the process (launchd/systemd) with restart policies for transient edge drops"],"tags":["network","tunnel","edge-connection","firewall"],"backgroundTag":"network-request-failed","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}