cloudflare/cloudflared · error

Invalid hostname provided

Error message

Invalid hostname provided

What it means

TunnelCommand validates the --hostname flag with validation.ValidateHostname before using it; when the value is not an acceptable hostname (empty, illegal characters, oversized labels, malformed punycode, etc.) the validation error is wrapped as 'Invalid hostname provided'. This guards the DNS route that will be created for the tunnel, since an invalid hostname would fail later at the Cloudflare API anyway.

Source

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

		Flags:       tunnelFlags(false),
	}
}

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 != "" {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Check the value passed to --hostname: it must be a bare, valid DNS hostname like app.example.com (no scheme, path, or spaces).
2. Strip scheme/path if you copied a URL: use --hostname app.example.com, not https://app.example.com/route.
3. Ensure --hostname is non-empty; if you don't want a hostname, omit the flag entirely instead of passing an empty string.
4. Punycode internationalized names before passing them (e.g. xn--bcher-kva.example).

Example fix

// before
cloudflared tunnel run --name mytunnel --hostname https://app.example.com/

// after
cloudflared tunnel run --name mytunnel --hostname app.example.com

import "golang.org/x/net/idna"
func validHostname(h string) bool {
    if h == "" || strings.Contains(h, "://") || strings.ContainsAny(h, " /\t") { return false }
    _, err := idna.Lookup.ToASCII(h)
    return err == nil
}
// call before: cloudflared tunnel run --hostname $HOSTNAME_ARG

if err := runTunnel(); err != nil && strings.Contains(err.Error(), "Invalid hostname provided") { t.Fatalf("check --hostname value: %v", err) }

When it happens

Trigger: `cloudflared tunnel --hostname <value> ...` where <value> fails ValidateHostname: contains spaces or invalid characters, has empty labels (a..b), exceeds 253 chars or 63-char label limit, uses bad punycode, or is an empty string passed explicitly via --hostname "" with --name set.

Common situations: Typos in the hostname; quoting mistakes leaving stray characters or empty value; copying a full URL (https://example.com) instead of a bare hostname; IDN hostnames not properly punycoded; shell variable expanding to empty.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid Host provided
• not a valid host
• no input provided
• failed to parse Host
• ErrInvalidTunnelID

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