caddyserver/caddy · error

network '%s' cannot handle HTTP/3 connections

Error message

network '%s' cannot handle HTTP/3 connections

What it means

getHTTP3Network looks the network string up in the HTTP/3 network registry (populated by RegisterNetworkHTTP3); if the lowercase network name is absent it returns this error. It is the inner error behind 533 and means the network type fundamentally cannot carry QUIC/HTTP3 in this build.

Source

Thrown at modules/caddyhttp/server.go:1514

	"fdgram":   "fdgram",
}

// RegisterNetworkHTTP3 registers a mapping from non-HTTP/3 network to HTTP/3
// network. This should be called during init() and will panic if the network
// type is standard, reserved, or already registered.
//
// EXPERIMENTAL: Subject to change.
func RegisterNetworkHTTP3(originalNetwork, h3Network string) {
	if _, ok := networkTypesHTTP3[strings.ToLower(originalNetwork)]; ok {
		panic("network type " + originalNetwork + " is already registered")
	}
	networkTypesHTTP3[originalNetwork] = h3Network
}

func getHTTP3Network(originalNetwork string) (string, error) {
	h3Network, ok := networkTypesHTTP3[strings.ToLower(originalNetwork)]
	if !ok {
		return "", fmt.Errorf("network '%s' cannot handle HTTP/3 connections", originalNetwork)
	}
	return h3Network, nil
}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Switch the listener to a registered network (tcp/tcp4/tcp6 map to udp equivalents)
2. Register an HTTP/3 mapping for the custom network with caddyhttp.RegisterNetworkHTTP3
3. Turn off h3 for that listener via the server's protocols option

Example fix

// before
_, err := caddyhttp.GetHTTP3NetworkLike("unix") // hypothetical

// after: only registered networks
// tcp -> udp; register custom ones first:
func init() { caddyhttp.RegisterNetworkHTTP3("unixgram", "unixgram") }

var h3Networks = map[string]bool{"tcp": true, "tcp4": true, "tcp6": true}

func canServeH3(network string) bool {
    return h3Networks[strings.ToLower(network)] // extend after RegisterNetworkHTTP3 calls
}

When it happens

Trigger: Calling code or configs referencing networks like "unix" or unregistered custom types when HTTP/3 is requested; invoking serveHTTP3 on a network never registered via caddyhttp.RegisterNetworkHTTP3.

Common situations: Plugin/embedded use of Caddy that serves HTTP/3 on custom networks; stock builds binding unix sockets while h3 is enabled.

Related errors

• starting HTTP/3 QUIC listener: %v
• network type %s is already registered
• download failed: %v
• listening on %s: %v
• network '%s' cannot handle HTTP/1 or HTTP/2 connections

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