{"record":{"id":"a1f894a120805bd8","repo":"caddyserver/caddy","slug":"network-s-cannot-handle-http-3-connections","errorCode":null,"errorMessage":"network '%s' cannot handle HTTP/3 connections","messagePattern":"network '(.+?)' cannot handle HTTP/3 connections","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/server.go","lineNumber":1514,"sourceCode":"\t\"fdgram\":   \"fdgram\",\n}\n\n// RegisterNetworkHTTP3 registers a mapping from non-HTTP/3 network to HTTP/3\n// network. This should be called during init() and will panic if the network\n// type is standard, reserved, or already registered.\n//\n// EXPERIMENTAL: Subject to change.\nfunc RegisterNetworkHTTP3(originalNetwork, h3Network string) {\n\tif _, ok := networkTypesHTTP3[strings.ToLower(originalNetwork)]; ok {\n\t\tpanic(\"network type \" + originalNetwork + \" is already registered\")\n\t}\n\tnetworkTypesHTTP3[originalNetwork] = h3Network\n}\n\nfunc getHTTP3Network(originalNetwork string) (string, error) {\n\th3Network, ok := networkTypesHTTP3[strings.ToLower(originalNetwork)]\n\tif !ok {\n\t\treturn \"\", fmt.Errorf(\"network '%s' cannot handle HTTP/3 connections\", originalNetwork)\n\t}\n\treturn h3Network, nil\n}\n","sourceCodeStart":1496,"sourceCodeEnd":1518,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/server.go#L1496-L1518","documentation":"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.","triggerScenarios":"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.","commonSituations":"Plugin/embedded use of Caddy that serves HTTP/3 on custom networks; stock builds binding unix sockets while h3 is enabled.","solutions":["Switch the listener to a registered network (tcp/tcp4/tcp6 map to udp equivalents)","Register an HTTP/3 mapping for the custom network with caddyhttp.RegisterNetworkHTTP3","Turn off h3 for that listener via the server's protocols option"],"exampleFix":"// before\n_, err := caddyhttp.GetHTTP3NetworkLike(\"unix\") // hypothetical\n\n// after: only registered networks\n// tcp -> udp; register custom ones first:\nfunc init() { caddyhttp.RegisterNetworkHTTP3(\"unixgram\", \"unixgram\") }","handlingStrategy":"validation","validationCode":"var h3Networks = map[string]bool{\"tcp\": true, \"tcp4\": true, \"tcp6\": true}\n\nfunc canServeH3(network string) bool {\n    return h3Networks[strings.ToLower(network)] // extend after RegisterNetworkHTTP3 calls\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check network support before enabling h3 in embedded scenarios","Register custom network mappings at init time, before any server starts"],"tags":["caddy","http3","network","registry","embedding"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}