cloudflare/cloudflared · error

Hostname %s has invalid ASCII encdoing %s

Error message

Hostname %s has invalid ASCII encdoing %s

What it means

For plain (non-URL) hostname input, ValidateHostname converts the hostname to ASCII via idna.ToASCII. This error is returned when the bare hostname fails IDNA conversion — invalid characters, bad label structure, or non-encodable Unicode.

Source

Thrown at validation/validation.go:52

	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

}

// ValidateUrl returns a validated version of `originUrl` with a scheme prepended (by default http://).
// Note: when originUrl contains a scheme, the path is removed:
//
//	ValidateUrl("https://localhost:8080/api/") => "https://localhost:8080"
//
// but when it does not, the path is preserved:
//
//	ValidateUrl("localhost:8080/api/") => "http://localhost:8080/api/"
//

View on GitHub (pinned to 2253eeeb25)

Solutions

  1. Use a valid RFC hostname: letters, digits, hyphens only, no leading/trailing hyphens, labels ≤ 63 chars
  2. Replace underscores with hyphens or use the IP address directly
  3. Pre-validate with idna.ToASCII(hostname) before calling
  4. Strip hidden/zero-width unicode characters from the input

Example fix

// before
hostname, err := validation.ValidateHostname("my_server.example.com")
// after
hostname, err := validation.ValidateHostname("my-server.example.com")
Defensive patterns

Strategy: validation

Validate before calling

func validHostname(h string) bool {
    if h == "" { return false }
    _, err := idna.ToASCII(h)
    return err == nil
}

Try / catch

host, err := validation.ValidateHostname(input)
if err != nil {
    if strings.Contains(err.Error(), "invalid ASCII") {
        return fmt.Errorf("hostname %q is not IDNA-encodable; use letters, digits, hyphens", input)
    }
    return err
}

Prevention

When it happens

Trigger: Calling ValidateHostname with a hostname without ':' that idna.ToASCII rejects — e.g. "my_host" (underscore), "-bad-.example.com" (leading/trailing hyphen), a label over 63 characters, or non-UTF8 bytes.

Common situations: Config files with hostnames containing underscores (common internal-DNS habit that IDNA rejects); typos like double dots or stray dashes; hostnames pasted with hidden unicode characters.

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/7ddcc9cedb595d25. Report an issue: GitHub.