{"record":{"id":"6456940b9bd1cd21","repo":"caddyserver/caddy","slug":"network-s-cannot-handle-http-1-or-http-2-connec","errorCode":null,"errorMessage":"network '%s' cannot handle HTTP/1 or HTTP/2 connections","messagePattern":"network '(.+?)' cannot handle HTTP/1 or HTTP/2 connections","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/app.go","lineNumber":574,"sourceCode":"\t\t\t\t// enable TLS if there is a policy and if this is not the HTTP port\n\t\t\t\tuseTLS := len(srv.TLSConnPolicies) > 0 && int(listenAddr.StartPort+portOffset) != app.httpPort()\n\n\t\t\t\tif h1ok || h2ok && useTLS || h2cok {\n\t\t\t\t\t// create the listener for this socket\n\t\t\t\t\tlnAny, err := listenAddr.Listen(app.ctx, portOffset, net.ListenConfig{\n\t\t\t\t\t\tKeepAliveConfig: net.KeepAliveConfig{\n\t\t\t\t\t\t\tEnable:   srv.KeepAliveInterval >= 0,\n\t\t\t\t\t\t\tInterval: time.Duration(srv.KeepAliveInterval),\n\t\t\t\t\t\t\tIdle:     time.Duration(srv.KeepAliveIdle),\n\t\t\t\t\t\t\tCount:    srv.KeepAliveCount,\n\t\t\t\t\t\t},\n\t\t\t\t\t})\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn fmt.Errorf(\"listening on %s: %v\", listenAddr.At(portOffset), err)\n\t\t\t\t\t}\n\t\t\t\t\tln, ok := lnAny.(net.Listener)\n\t\t\t\t\tif !ok {\n\t\t\t\t\t\treturn fmt.Errorf(\"network '%s' cannot handle HTTP/1 or HTTP/2 connections\", listenAddr.Network)\n\t\t\t\t\t}\n\n\t\t\t\t\t// wrap listener before TLS (up to the TLS placeholder wrapper)\n\t\t\t\t\tvar lnWrapperIdx int\n\t\t\t\t\tfor i, lnWrapper := range srv.listenerWrappers {\n\t\t\t\t\t\tif _, ok := lnWrapper.(*tlsPlaceholderWrapper); ok {\n\t\t\t\t\t\t\tlnWrapperIdx = i + 1 // mark the next wrapper's spot\n\t\t\t\t\t\t\tbreak\n\t\t\t\t\t\t}\n\t\t\t\t\t\tln = lnWrapper.WrapListener(ln)\n\t\t\t\t\t}\n\n\t\t\t\t\tif useTLS {\n\t\t\t\t\t\t// create TLS listener - this enables and terminates TLS\n\t\t\t\t\t\tln = tls.NewListener(ln, tlsCfg)\n\t\t\t\t\t}\n\n\t\t\t\t\t// finish wrapping listener where we left off before TLS","sourceCodeStart":556,"sourceCodeEnd":592,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/app.go#L556-L592","documentation":"After successfully creating a socket for an HTTP-capable protocol set, Caddy asserts the returned object is a net.Listener (stream socket). Non-stream networks (e.g. unixgram, or packet-oriented networks) cannot serve HTTP/1 or HTTP/2, so Start rejects them with the network name from the listen address.","triggerScenarios":"Using a datagram/packet network in listen for a server whose protocols include h1/h2/h2c, e.g. \"unixgram//path/to/socket\" or ip4 networks; only quic-capable networks legitimately use packet conns via the HTTP/3 path.","commonSituations":"Trying to serve HTTP over a unixgram socket copied from a UDP example; mistaking the l4 module's network syntax for http server listen syntax.","solutions":["Use a stream network for HTTP servers: plain host:port (tcp) or unix/<path> (\"unix//tmp/caddy.sock\")","Reserve udp/GRAM networks for the automatic HTTP/3 handling, not explicit listen entries"],"exampleFix":"// before\n\"listen\": [\"unixgram//run/caddy.sock\"]\n// after\n\"listen\": [\"unix//run/caddy.sock\"]","handlingStrategy":"validation","validationCode":"for _, a := range srvCfg.Listen {\n    na, err := caddy.ParseNetworkAddress(a)\n    if err != nil { return err }\n    switch na.Network {\n    case \"\", \"tcp\", \"tcp4\", \"tcp6\", \"unix\":\n    default:\n        if !strings.Contains(na.Network, \"gram\") && na.Network != \"udp\" { /* ... */ }\n        return fmt.Errorf(\"network %q cannot serve HTTP/1-2; use tcp/unix\", na.Network)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use tcp (default) or unix networks for HTTP servers","Leave udp/QUIC to Caddy's automatic HTTP/3 handling on the same tcp listener"],"tags":["caddy","listener","network","unix","startup"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}