hostname and url shouldn't match. See --help for more inform

Error message

hostname and url shouldn't match. See --help for more information

What it means

When running an ad-hoc named tunnel via 'cloudflared tunnel run', the --hostname and --url flags must not be identical, because that would map the tunnel to itself and create a nonsensical route. The pre-flight check in TunnelCommand rejects this configuration.

Source

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

func TunnelCommand(c *cli.Context) error {
	sc, err := newSubcommandContext(c)
	if err != nil {
		return err
	}

	// Run an adhoc named tunnel
	// Allows for the creation, routing (optional), and startup of a tunnel in one command
	// --name required
	// --url or --hello-world required
	// --hostname optional
	if name := c.String(cfdflags.Name); name != "" {
		hostname, err := validation.ValidateHostname(c.String("hostname"))
		if err != nil {
			return errors.Wrap(err, "Invalid hostname provided")
		}
		tunnelURL := c.String("url")
		if tunnelURL == hostname && tunnelURL != "" && hostname != "" {
			return fmt.Errorf("hostname and url shouldn't match. See --help for more information")
		}

		return runAdhocNamedTunnel(sc, name, c.String(CredFileFlag))
	}

	// Run a quick tunnel
	// A unauthenticated named tunnel hosted on <random>.<quick-tunnels-service>.com
	shouldRunQuickTunnel := c.IsSet("url") || c.IsSet(ingress.HelloWorldFlag)
	if c.String("quick-service") != "" && shouldRunQuickTunnel {
		return RunQuickTunnel(sc)
	}

	// If user provides a config, check to see if they meant to use `tunnel run` instead
	if ref := config.GetConfiguration().TunnelID; ref != "" {
		return fmt.Errorf("use `cloudflared tunnel run` to start tunnel %s", ref)
	}

	// Classic tunnel usage is no longer supported

View on GitHub (pinned to 2253eeeb25)

Solutions

Set --hostname to the public DNS name and --url to the local origin address; they must differ
Omit --hostname if you only want a local origin run without routing
Review `cloudflared tunnel run --help` for flag semantics

Example fix

# before
cloudflared tunnel run --hostname localhost --url localhost mytunnel
# after
cloudflared tunnel run --hostname app.example.com --url http://localhost:8080 mytunnel

Defensive patterns

Strategy: validation

Validate before calling

hostname, _ := validation.ValidateHostname(hostnameFlag)
if urlFlag != "" && hostname != "" && urlFlag == hostname {
	return errors.New("--hostname and --url must differ")
}

Try / catch

if err := TunnelCommand(ctx, sc, c); err != nil {
	if strings.Contains(err.Error(), "hostname and url shouldn't match") {
		// fix flags: --hostname is public name, --url is local origin
	}
	return err
}

Prevention

Treat --hostname as the public ingress name and --url as the local service address
Never pass the same value to both flags
Verify flags in wrapper scripts before invoking cloudflared tunnel run

When it happens

Trigger: Running e.g. `cloudflared tunnel run --hostname localhost --url localhost <name>` — tunnelURL == hostname, both non-empty.

Common situations: Copy-pasting the same value into both flags, misunderstanding that --hostname is the public ingress hostname (e.g. app.example.com) while --url is the local origin service (e.g. http://localhost:8080).

Related errors

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