errDeprecatedClassicTunnel

errDeprecatedClassicTunnel

Error message

Classic tunnels have been deprecated, please use Named Tunnels. (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)

What it means

Classic (hostname-routed) tunnels were retired; cloudflared only supports Named Tunnels. TunnelCommand returns errDeprecatedClassicTunnel when it detects classic-tunnel usage via the --hostname flag, pointing users at the Named Tunnels migration guide.

Source

Thrown at cmd/cloudflared/tunnel/cmd.go:74

tunnelCmdErrorMessage = `You did not specify any valid additional argument to the cloudflared tunnel command.

If you are trying to run a Quick Tunnel then you need to explicitly pass the --url flag.
Eg. cloudflared tunnel --url localhost:8080/.

Please note that Quick Tunnels are meant to be ephemeral and should only be used for testing purposes.
For production usage, we recommend creating Named Tunnels. (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)
`
)

var (
graceShutdownC chan struct{}
buildInfo *cliutil.BuildInfo

routeFailMsg = fmt.Sprintf("failed to provision routing, please create it manually via Cloudflare dashboard or UI; "+
"most likely you already have a conflicting record there. You can also rerun this command with --%s to overwrite "+
"any existing DNS records for this hostname.", overwriteDNSFlag)
errDeprecatedClassicTunnel = errors.New("Classic tunnels have been deprecated, please use Named Tunnels. (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)")
// TODO: TUN-8756 the list below denotes the flags that do not possess any kind of sensitive information
// however this approach is not maintainble in the long-term.
nonSecretFlagsList = []string{
"config",
cfdflags.AutoUpdateFreq,
cfdflags.NoAutoUpdate,
cfdflags.NoPrechecks,
cfdflags.Metrics,
"pidfile",
"url",
"hello-world",
"socks5",
"proxy-connect-timeout",
"proxy-tls-timeout",
"proxy-tcp-keepalive",
"proxy-no-happy-eyeballs",
"proxy-keepalive-connections",
"proxy-keepalive-timeout",

View on GitHub (pinned to 2253eeeb25)

Solutions

Remove --hostname from the command/config and create a Named Tunnel: `cloudflared tunnel create <name>`.
Route the tunnel with `cloudflared tunnel route dns <tunnel> <hostname>` instead of --hostname.
Migrate per the linked guide: log in with `cloudflared tunnel login`, use tunnel credentials file/`--token`, and define ingress in config.yml.
If running via dashboard remotely-managed tunnels, install the service with the tunnel token instead.

Example fix

# before (classic)
cloudflared tunnel --hostname app.example.com --url http://localhost:8080
# after (named)
cloudflared tunnel create my-tunnel
cloudflared tunnel route dns my-tunnel app.example.com
cloudflared tunnel run my-tunnel

Defensive patterns

Strategy: validation

Validate before calling

for a in "$@"; do
  if [ "$a" = "--hostname" ]; then
    echo "classic tunnels are deprecated; use Named Tunnels (tunnel create + route dns)"; exit 2
  fi
done

Try / catch

if err := cmd.Run(); err != nil {
    if strings.Contains(err.Error(), "Classic tunnels have been deprecated") {
        return migrateToNamedTunnel(ctx) // automated migration path
    }
    return err
}

Prevention

Remove --hostname from all tunnel commands and config files.
Use Named Tunnels exclusively: create, route dns, run (or remote-managed via dashboard token).
Search repos/docs for `--hostname` alongside `cloudflared tunnel` and update playbooks.

When it happens

Trigger: Running `cloudflared tunnel` (e.g. `tunnel create`/run flows) with --hostname set — the flag combination that used to signal a classic, hostname-bound tunnel.

Common situations: Old scripts/config files from pre-2021 setups using `cert.pem` + `--hostname`; migration from legacy tunnels to Zero Trust Named Tunnels; tutorials predating Named Tunnels.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/7d504869e4a3ff1a. Report an issue: GitHub.