the scheme wss:// is only supported in browsers; use https:/

Error message

the scheme wss:// is only supported in browsers; use https:// instead

What it means

A site address key used the wss:// scheme. Caddy rejects it because wss:// is a browser-only API concept (WebSocket-over-TLS); the server should be described as https:// and it will serve WebSockets over TLS automatically.

Source

Thrown at caddyconfig/httpcaddyfile/addresses.go:275

			sbaddrs = append(sbaddrs, sbAddrAssociation{
				addressesWithProtocols: addressesWithProtocols,
				serverBlocks:           serverBlocks,
			})
		}
	}

	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))
	}

View on GitHub (pinned to 50e54ee279)

Solutions

Change wss:// to https:// in the site label; WebSocket upgrade handling is automatic
Keep clients using wss:// to connect — only the Caddyfile label changes

Example fix

# before
wss://example.com {
}
# after
https://example.com {
}

Defensive patterns

Strategy: validation

Validate before calling

if strings.HasPrefix(siteKey, "wss://") {
    return errors.New("use https:// for site addresses; clients keep wss://")
}

Prevention

Treat wss:// as client-only vocabulary
Template site labels from https://, not from frontend WebSocket URLs

When it happens

Trigger: A Caddyfile site block key starts with wss://, e.g. 'wss://example.com { }'. listenersForServerBlockAddress rejects the scheme before any listener is built.

Common situations: Copy-pasting a client-side WebSocket URL from JavaScript (new WebSocket('wss://...')) into a Caddyfile as the site address.

Related errors

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