the scheme ws:// is only supported in browsers; use http://

Error message

the scheme ws:// is only supported in browsers; use http:// instead

What it means

A site address key used the ws:// scheme. Like wss://, it is a browser-side concept (WebSocket-over-HTTP); the server site should be http:// and Caddy serves WebSocket upgrades over plain HTTP automatically.

Source

Thrown at caddyconfig/httpcaddyfile/addresses.go:277

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

	// default port is the HTTPS port
	lnPort := httpsPort

View on GitHub (pinned to 50e54ee279)

Solutions

Change ws:// to http:// in the site label
Configure the reverse_proxy to the backend as usual; no special WebSocket directive is needed

Example fix

# before
ws://example.com:8080 {
}
# after
http://example.com:8080 {
}

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use http:// site labels for plain-HTTP WebSocket frontends
Remember Caddy proxies WebSockets without extra directives

When it happens

Trigger: A Caddyfile site block key starts with ws://, e.g. 'ws://example.com:8080 { }'.

Common situations: Using client WebSocket URLs (new WebSocket('ws://...')) as site addresses, often when reverse-proxying a WebSocket backend.

Related errors

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