{"record":{"id":"d29933d19dcf2875","repo":"cloudflare/cloudflared","slug":"use-cloudflared-tunnel-run-to-start-tunnel-s","errorCode":null,"errorMessage":"use `cloudflared tunnel run` to start tunnel %s","messagePattern":"use `cloudflared tunnel run` to start tunnel (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/tunnel/cmd.go","lineNumber":262,"sourceCode":"\t\t}\n\t\ttunnelURL := c.String(\"url\")\n\t\tif tunnelURL == hostname && tunnelURL != \"\" && hostname != \"\" {\n\t\t\treturn fmt.Errorf(\"hostname and url shouldn't match. See --help for more information\")\n\t\t}\n\n\t\treturn runAdhocNamedTunnel(sc, name, c.String(CredFileFlag))\n\t}\n\n\t// Run a quick tunnel\n\t// A unauthenticated named tunnel hosted on <random>.<quick-tunnels-service>.com\n\tshouldRunQuickTunnel := c.IsSet(\"url\") || c.IsSet(ingress.HelloWorldFlag)\n\tif c.String(\"quick-service\") != \"\" && shouldRunQuickTunnel {\n\t\treturn RunQuickTunnel(sc)\n\t}\n\n\t// If user provides a config, check to see if they meant to use `tunnel run` instead\n\tif ref := config.GetConfiguration().TunnelID; ref != \"\" {\n\t\treturn fmt.Errorf(\"use `cloudflared tunnel run` to start tunnel %s\", ref)\n\t}\n\n\t// Classic tunnel usage is no longer supported\n\tif c.String(\"hostname\") != \"\" {\n\t\treturn errDeprecatedClassicTunnel\n\t}\n\n\treturn errors.New(tunnelCmdErrorMessage)\n}\n\nfunc Init(info *cliutil.BuildInfo, gracefulShutdown chan struct{}) {\n\tbuildInfo, graceShutdownC = info, gracefulShutdown\n}\n\n// runAdhocNamedTunnel create, route and run a named tunnel in one command\nfunc runAdhocNamedTunnel(sc *subcommandContext, name, credentialsOutputPath string) error {\n\ttunnel, ok, err := sc.tunnelActive(name)\n\tif err != nil || !ok {","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/tunnel/cmd.go#L244-L280","documentation":"cloudflared refuses to start a tunnel when the configuration file already contains a tunnel ID, because providing a TunnelID means `tunnel run` semantics were intended, not `tunnel` (proxy-dns style) invocation. The library throws this to catch users who configured a tunnel but invoked the wrong subcommand. It is a guard against running named tunnels without the proper `run` command flow.","triggerScenarios":"Running `cloudflared tunnel` (or an embedded TunnelCommand via the CLI app) when the resolved config file has `tunnel: <ID>` set, instead of running `cloudflared tunnel run`. Also triggered by script wrappers that call TunnelCommand directly with a config containing TunnelID.","commonSituations":"Users follow an old tutorial that says `cloudflared tunnel <UUID>` as a positional argument style; or a systemd unit / Docker entrypoint invokes `cloudflared tunnel` with a config file that lists tunnel ID. Also common after moving credentials into config but forgetting to change the command to `run`.","solutions":["Change the command to `cloudflared tunnel run` (optionally with `--token` or credentials flags).","If you really intend non-run behavior, remove the `tunnel:` (TunnelID) entry from the config file or unset it via `TUNNEL_ID` env override.","If embedding cloudflared, invoke the `tunnel run` action instead of the bare TunnelCommand when configuration contains a tunnel ID."],"exampleFix":"// before\nExecStart=/usr/local/bin/cloudflared tunnel --config /etc/cloudflared/config.yml\n// after\nExecStart=/usr/local/bin/cloudflared tunnel --config /etc/cloudflared/config.yml run","handlingStrategy":"validation","validationCode":"// shell: fail fast if config declares a tunnel ID\nif grep -qE '^tunnel:' /etc/cloudflared/config.yml; then\n  exec cloudflared tunnel --config /etc/cloudflared/config.yml run\nfi\nexec cloudflared tunnel --config /etc/cloudflared/config.yml","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use `tunnel run` once a tunnel ID or token exists in config.","Keep positional-argument style (`cloudflared tunnel <ID>`) out of scripts and units.","Validate deployment templates against the current cloudflared command surface after upgrades."],"tags":["cli","configuration","tunnel"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}