What causes "URL should not be empty" in cloudflare/cloudflared?

Provide a non-empty origin URL, e.g. --url http://localhost:8080 or service: http://localhost:8080 in config

URL should not be empty

Error message

URL should not be empty

What it means

validateUrlString is the internal normalizer behind ValidateUrl and NewAccessValidator; it rejects an empty origin URL up front because no scheme/host can be derived from an empty string. The library requires a non-empty URL string to validate and prepend a default scheme to.

Source

Thrown at validation/validation.go:82

//
//	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/"
//
// This is arguably a bug, but changing it might break some cloudflared users.
func ValidateUrl(originUrl string) (*url.URL, error) {
	urlStr, err := validateUrlString(originUrl)
	if err != nil {
		return nil, err
	}
	return url.Parse(urlStr)
}

func validateUrlString(originUrl string) (string, error) {
	if originUrl == "" {
		return "", fmt.Errorf("URL should not be empty")
	}

	if net.ParseIP(originUrl) != nil {
		return validateIP("", originUrl, "")
	} else if strings.HasPrefix(originUrl, "[") && strings.HasSuffix(originUrl, "]") {
		// ParseIP doesn't recoginze [::1]
		return validateIP("", originUrl[1:len(originUrl)-1], "")
	}

	host, port, err := net.SplitHostPort(originUrl)
	// user might pass in an ip address like 127.0.0.1
	if err == nil && net.ParseIP(host) != nil {
		return validateIP("", host, port)
	}

	unescapedUrl, err := url.PathUnescape(originUrl)
	if err != nil {
		return "", fmt.Errorf("URL %s has invalid escape characters %s", originUrl, unescapedUrl)

View on GitHub (pinned to 2253eeeb25)

Solutions

Provide a non-empty origin URL, e.g. --url http://localhost:8080 or service: http://localhost:8080 in config
Check the config file/env var feeding the value is actually set and non-empty before calling
Add an early guard in your code that skips/errs on empty URLs with a clearer message
If the value may legitimately be absent, check for emptiness before invoking ValidateUrl

Example fix

// before
u, err := validation.ValidateUrl(os.Getenv("ORIGIN_URL")) // empty env var
// after
origin := os.Getenv("ORIGIN_URL")
if origin == "" {
    return nil, errors.New("ORIGIN_URL is not set")
}
u, err := validation.ValidateUrl(origin)

Defensive patterns

Strategy: validation

Validate before calling

func nonEmptyURL(s string) bool { return strings.TrimSpace(s) != "" }

Try / catch

u, err := validation.ValidateUrl(origin)
if err != nil {
    if err.Error() == "URL should not be empty" {
        return nil, fmt.Errorf("origin URL is required; set the --url flag or service config")
    }
    return nil, err
}

Prevention

Check that config fields/env vars feeding URLs are set and non-empty before calling
Use required-field checks when loading tunnel configuration files
Provide explicit defaults (e.g. http://localhost:8080) instead of empty strings

When it happens

Trigger: Calling ValidateUrl("") or NewAccessValidator with an empty domain or issuer string — typically an unset config value or environment variable for the origin/issuer URL.

Common situations: Config file missing the origin/ingress service value; empty environment variable substituted into the URL field; YAML/JSON config key present but with an empty value; programmatic callers passing an empty string default.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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