caddyserver/caddy · error

unsupported URL scheme %s://

Error message

unsupported URL scheme %s://

What it means

The site address scheme is none of http, https, ws, wss, or empty — Caddy does not know how to serve it. The message echoes the scheme so the offending label is obvious.

Source

Thrown at caddyconfig/httpcaddyfile/addresses.go:281

	}

	return sbaddrs
}

// listenersForServerBlockAddress essentially converts the Caddyfile site addresses to a map from
// Caddy listener addresses and the protocols to serve them with to the parsed address for each server block.
func (st *ServerType) listenersForServerBlockAddress(sblock serverBlock, addr Address,
	options map[string]any,
) (map[string]map[string]struct{}, error) {
	switch addr.Scheme {
	case "wss":
		return nil, fmt.Errorf("the scheme wss:// is only supported in browsers; use https:// instead")
	case "ws":
		return nil, fmt.Errorf("the scheme ws:// is only supported in browsers; use http:// instead")
	case "https", "http", "":
		// Do nothing or handle the valid schemes
	default:
		return nil, fmt.Errorf("unsupported URL scheme %s://", addr.Scheme)
	}

	// figure out the HTTP and HTTPS ports; either
	// use defaults, or override with user config
	httpPort, httpsPort := strconv.Itoa(caddyhttp.DefaultHTTPPort), strconv.Itoa(caddyhttp.DefaultHTTPSPort)
	if hport, ok := options["http_port"]; ok {
		httpPort = strconv.Itoa(hport.(int))
	}
	if hsport, ok := options["https_port"]; ok {
		httpsPort = strconv.Itoa(hsport.(int))
	}

	// default port is the HTTPS port
	lnPort := httpsPort
	if addr.Port != "" {
		// port explicitly defined
		lnPort = addr.Port
	} else if addr.Scheme == "http" {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Remove or correct the scheme; site addresses accept no scheme, http://, or https://
2. If you meant a proxy target, put that URL in reverse_proxy, not in the site label
3. For non-HTTP listeners, use the global servers/layer4-style plugins rather than an HTTP site address

Example fix

# before
ftp://example.com {
}
# after
example.com {
}

var schemeRe = regexp.MustCompile(`^(https?://)?`)
if !schemeRe.MatchString(siteKey) || strings.Contains(siteKey, "://") && !strings.HasPrefix(siteKey, "http://") && !strings.HasPrefix(siteKey, "https://") {
    return fmt.Errorf("site address %q must use http, https, or no scheme", siteKey)
}

func isSupportedScheme(s string) bool {
    switch s {
    case "", "http", "https":
        return true
    }
    return false
}

When it happens

Trigger: A site key with an arbitrary scheme such as ftp://example.com or tcp://example.com; only http/https (and their WebSocket browser aliases, which get their own errors) are valid for site addresses.

Common situations: Confusing Caddy site addresses with proxy upstream URLs (e.g. writing fastcgi:// or tcp:// as a site label), or typos like 'httpss://'.

Related errors

• the scheme wss:// is only supported in browsers; use https:/
• the scheme ws:// is only supported in browsers; use http://
• [%s] scheme and port violate convention
• parsing key: %v
• server block %d, key %d (%s): determining listener address:

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/1f05c8b9df441f23. Report an issue: GitHub.