What causes "not a valid host" in cloudflare/cloudflared?

Include the full scheme and host: use https://app.example.com/path instead of app.example.com/path

not a valid host

Error message

not a valid host

What it means

processURL parses the user-supplied URL with url.ParseRequestURI and then requires a non-empty Host component; an empty host yields this error. It means the string was parseable as a URI but lacked an authority, so an Access token cannot be fetched for it.

Source

Thrown at cmd/cloudflared/access/cmd.go:502

func parseAllowRequest(cmdArgs []string) ([]string, bool) {
	if len(cmdArgs) > 1 {
		if cmdArgs[0] == "--allow-request" || cmdArgs[0] == "-ar" {
			return cmdArgs[1:], true
		}
	}

	return cmdArgs, false
}

// processURL will preprocess the string (parse to a url, convert to punycode, etc).
func processURL(s string) (*url.URL, error) {
	u, err := url.ParseRequestURI(s)
	if err != nil {
		return nil, err
	}

	if u.Host == "" {
		return nil, errors.New("not a valid host")
	}

	host, err := idna.ToASCII(u.Hostname())
	if err != nil { // we fail to convert to punycode, just return the url we parsed.
		return u, nil
	}
	if u.Port() != "" {
		u.Host = fmt.Sprintf("%s:%s", host, u.Port())
	} else {
		u.Host = host
	}

	return u, nil
}

// cloudflaredPath pulls the full path of cloudflared on disk
func cloudflaredPath() string {
	path, err := os.Executable()

View on GitHub (pinned to 2253eeeb25)

Solutions

Include the full scheme and host: use https://app.example.com/path instead of app.example.com/path
Quote the URL in the shell to prevent splitting/truncation
Check for stray characters or line breaks that truncated the URL
Verify with a quick parse (e.g. `python3 -c "import urllib.parse;print(urllib.parse.urlparse('YOUR_URL').netloc)"`) that a host is present

Example fix

// before
# cloudflared access curl app.example.com
// after
# cloudflared access curl https://app.example.com

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.ParseRequestURI(target)
if err != nil || u.Host == "" {
    return fmt.Errorf("%q must be an absolute URL with a host, e.g. https://app.example.com", target)
}

Try / catch

u, err := processURL(target)
if err != nil {
    if strings.Contains(err.Error(), "not a valid host") {
        return fmt.Errorf("URL %q is missing a host; include the scheme (https://...): %w", target, err)
    }
    return err
}

Prevention

Always use absolute URLs including the https:// scheme
Quote URLs in shells to avoid truncation/splitting
Copy full URLs from the browser address bar, not relative paths
Trim whitespace and control characters from user-supplied URLs

When it happens

Trigger: Passing URLs without a host to `cloudflared access curl`, e.g. "/api/endpoint", "app.example.com/route" (no scheme but treated as a path), or an accidentally truncated URL like "https://".

Common situations: Omitting the scheme so the host becomes part of the path; passing a relative path copied from browser devtools; shell splitting a URL containing special characters; trailing-slash/whitespace truncation in scripts.

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