{"record":{"id":"913d2a1b53d01e7e","repo":"kubernetes/kops","slug":"error-listening-on-q-v","errorCode":null,"errorMessage":"error listening on %q: %v","messagePattern":"error listening on %q: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/kube-apiserver-healthcheck/main.go","lineNumber":185,"sourceCode":"\t\t}\n\n\t\ttlsConfig.Certificates = []tls.Certificate{keypair}\n\t}\n\n\ttransport := &http.Transport{\n\t\tTLSClientConfig: tlsConfig,\n\t}\n\n\ts := &healthCheckServer{\n\t\ttransport: transport,\n\t}\n\n\thttp.HandleFunc(\"/\", s.handler)\n\n\tklog.Infof(\"listening on %s\", listen)\n\n\tif err := http.ListenAndServe(listen, nil); err != nil {\n\t\treturn fmt.Errorf(\"error listening on %q: %v\", listen, err)\n\t}\n\n\treturn fmt.Errorf(\"unexpected return from ListenAndServe\")\n}\n\nfunc main() {\n\tif err := run(); err != nil {\n\t\tfmt.Fprintf(os.Stderr, \"%v\\n\", err)\n\t\tos.Exit(1)\n\t}\n}\n","sourceCodeStart":167,"sourceCodeEnd":197,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/cmd/kube-apiserver-healthcheck/main.go#L167-L197","documentation":"The healthcheck server fails when http.ListenAndServe cannot bind/serve on the configured --listen address. Common causes are the port already in use, an invalid address, or insufficient privileges for the port. The wrapped error includes the listen address and OS error.","triggerScenarios":"run() calls http.ListenAndServe(listen, nil) and the OS returns e.g. 'address already in use', 'permission denied' (port <1024 as non-root), or 'invalid address'.","commonSituations":"Another process (or a previous unclean pod) holds the port; two sidecars with the same --listen; binding :443 without NET_BIND_SERVICE; malformed host:port string.","solutions":["Check for a port conflict: ss -ltnp / lsof -i :<port> and kill the conflicting process or change --listen.","Use a non-privileged port (e.g. 3990) or grant the bind capability (setcap / securityContext).","Verify the --listen address syntax is valid host:port.","Ensure only one healthcheck instance runs per pod/netns."],"exampleFix":"// before\nrun(\"--listen\", \"0.0.0.0:443\", ...) // as non-root\n// after\nrun(\"--listen\", \"0.0.0.0:3990\", ...)","handlingStrategy":"validation","validationCode":"// check the port is free before binding\nln, err := net.Listen(\"tcp\", listen)\nif err != nil {\n    return fmt.Errorf(\"cannot bind %s: %w\", listen, err)\n}\nln.Close()","typeGuard":null,"tryCatchPattern":"// Go: handle bind failure with a clear operator message\nif err := run(); err != nil {\n    if strings.Contains(err.Error(), \"error listening\") {\n        klog.Fatalf(\"port conflict or bad address: %v\", err)\n    }\n}","preventionTips":["Use an unprivileged port (e.g. 3990) for the healthcheck sidecar.","Detect port conflicts with ss/lsof before deploying.","Never run two instances with the same --listen in one netns.","Validate the --listen address format in config templating."],"tags":["network","http-server","port-binding","healthcheck"],"backgroundTag":"address-already-in-use","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}