What causes "Hostname(actually a URL) %s has invalid format %s" in cloudflare/cloudflared?

Fix the URL syntax: close IPv6 brackets (http://[::1]:8080), use a numeric port, remove control characters

Hostname(actually a URL) %s has invalid format %s

Error message

Hostname(actually a URL) %s has invalid format %s

What it means

ValidateHostname detects a URL-like input (contains ':' or '%3A'), unescapes it, and calls url.Parse. This error is returned when the unescaped string still fails url.Parse, i.e. the input is not a syntactically valid URL.

Source

Thrown at validation/validation.go:41

var (
	supportedProtocols = []string{"http", "https", "rdp", "ssh", "smb", "tcp"}
	validationTimeout  = time.Duration(30 * time.Second)
)

func ValidateHostname(hostname string) (string, error) {
	if hostname == "" {
		return "", nil
	}
	// users gives url(contains schema) not just hostname
	if strings.Contains(hostname, ":") || strings.Contains(hostname, "%3A") {
		unescapeHostname, err := url.PathUnescape(hostname)
		if err != nil {
			return "", fmt.Errorf("Hostname(actually a URL) %s has invalid escape characters %s", hostname, unescapeHostname)
		}
		hostnameToURL, err := url.Parse(unescapeHostname)
		if err != nil {
			return "", fmt.Errorf("Hostname(actually a URL) %s has invalid format %s", hostname, hostnameToURL)
		}
		asciiHostname, err := idna.ToASCII(hostnameToURL.Hostname())
		if err != nil {
			return "", fmt.Errorf("Hostname(actually a URL) %s has invalid ASCII encdoing %s", hostname, asciiHostname)
		}
		return asciiHostname, nil
	}

	asciiHostname, err := idna.ToASCII(hostname)
	if err != nil {
		return "", fmt.Errorf("Hostname %s has invalid ASCII encdoing %s", hostname, asciiHostname)
	}
	hostnameToURL, err := url.Parse(asciiHostname)
	if err != nil {
		return "", fmt.Errorf("Hostname %s is not valid", hostnameToURL)
	}
	return hostnameToURL.RequestURI(), nil

View on GitHub (pinned to 2253eeeb25)

Solutions

Fix the URL syntax: close IPv6 brackets (http://[::1]:8080), use a numeric port, remove control characters
Pass a bare hostname instead of a URL if only a host is intended
Pre-validate the input with url.Parse before calling ValidateHostname
Percent-encode spaces/unsafe characters properly within the URL

Example fix

// before
hostname, err := validation.ValidateHostname("http://[::1")
// after
hostname, err := validation.ValidateHostname("[::1]")

Defensive patterns

Strategy: validation

Validate before calling

func parsableURL(s string) bool {
    if !strings.Contains(s, ":") { return true }
    unesc, err := url.PathUnescape(s)
    if err != nil { return false }
    _, err = url.Parse(unesc)
    return err == nil
}

Try / catch

host, err := validation.ValidateHostname(input)
if err != nil {
    if strings.Contains(err.Error(), "invalid format") {
        if _, perr := url.Parse(input); perr != nil {
            return fmt.Errorf("%q is not a valid URL: %v", input, perr)
        }
    }
    return err
}

Prevention

Validate the URL with url.Parse before passing URL-shaped values
Close IPv6 brackets and use numeric ports
Strip whitespace/control characters from config values

When it happens

Trigger: Calling ValidateHostname with a URL-shaped string containing ':' or '%3A' that url.Parse rejects, e.g. "http://[::1" (unclosed bracket) or "example.com:port" with a non-numeric port.

Common situations: Users passing a malformed URL where a hostname is expected — bad IPv6 brackets, invalid port, embedded spaces or control characters in the URL.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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