{"record":{"id":"957bbf48fb304207","repo":"caddyserver/caddy","slug":"listening-on-s-v","errorCode":null,"errorMessage":"listening on %s: %v","messagePattern":"listening on (.+?): (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"modules/caddyhttp/app.go","lineNumber":570,"sourceCode":"\n\t\t\tfor portOffset := uint(0); portOffset < listenAddr.PortRangeSize(); portOffset++ {\n\t\t\t\thostport := listenAddr.JoinHostPort(portOffset)\n\n\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","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/app.go#L552-L588","documentation":"The listener syscall failed: listenAddr.Listen could not bind the socket at the (possibly port-range-offset) address. The %s is the concrete address (listenAddr.At(portOffset)), %v the OS error such as 'address already in use' or 'permission denied'. This occurs at Start, after config is otherwise valid.","triggerScenarios":"Port already bound by another process or another Caddy server; binding to a privileged port (<1024) without capabilities; missing CAP_NET_BIND_SERVICE in containers; address family mismatch (IPv6 disabled); unix socket path already existing or in a non-writable directory.","commonSituations":"Two Caddy instances, or Caddy plus nginx/apache on :80/:443; docker port mappings conflicting; systemd socket activation already holding the port; SELinux denying bind.","solutions":["Find and stop the occupant: `ss -ltnp | grep <port>` (or `lsof -i :<port>`) then restart","For ports <1024, run with CAP_NET_BIND_SERVICE (`setcap cap_net_bind_service=+ep caddy`) or use a high port with redirection","Change the listen address/port in config if the conflict is with another intended service"],"exampleFix":"// before: caddy and nginx both on :443\n// after: nginx proxies to caddy on 127.0.0.1:8080; caddy listens there","handlingStrategy":"validation","validationCode":"// pre-flight: is the port free and bindable?\nfor _, a := range srvCfg.Listen {\n    na, _ := caddy.ParseNetworkAddress(a)\n    ln, err := net.Listen(na.Network, net.JoinHostPort(na.Host, strconv.Itoa(int(na.StartPort))))\n    if err != nil { return fmt.Errorf(\"cannot bind %s: %w\", a, err) }\n    ln.Close()\n}","typeGuard":null,"tryCatchPattern":"if err := caddy.Run(cfg); err != nil {\n    if strings.Contains(err.Error(), \"listening on\") {\n        // check occupancy: ss -ltnp / lsof, then retry once after freeing the port\n    }\n}","preventionTips":["Ensure only one reverse proxy owns :80/:443; chain proxies on loopback","Grant CAP_NET_BIND_SERVICE (setcap or systemd AmbientCapabilities) instead of running as root","In containers, avoid duplicating host port bindings across services"],"tags":["caddy","listener","network","bind","startup"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}