{"record":{"id":"b7dabbf7f14d0a63","repo":"istio/istio","slug":"unable-to-listen-on-socket-v","errorCode":null,"errorMessage":"unable to listen on socket: %v","messagePattern":"unable to listen on socket: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pilot/pkg/bootstrap/monitoring.go","lineNumber":87,"sourceCode":"\t\t\thttp.Error(w, \"Only requests from localhost are allowed\", http.StatusForbidden)\n\t\t\treturn\n\t\t}\n\t\t// Pass control back to the handler\n\t\thandler.ServeHTTP(w, r)\n\t})\n}\n\n// Deprecated: we shouldn't have 2 http ports. Will be removed after code using\n// this port is removed.\nfunc startMonitor(exporter http.Handler, addr string, mux *http.ServeMux) (*monitor, error) {\n\tm := &monitor{}\n\n\t// get the network stuff setup\n\tvar listener net.Listener\n\tif addr != \"\" {\n\t\tvar err error\n\t\tif listener, err = net.Listen(\"tcp\", addr); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"unable to listen on socket: %v\", err)\n\t\t}\n\t}\n\n\t// NOTE: this is a temporary solution to provide bare-bones debug functionality\n\t// for pilot. a full design / implementation of self-monitoring and reporting\n\t// is coming. that design will include proper coverage of statusz/healthz type\n\t// functionality, in addition to how pilot reports its own metrics.\n\taddMonitor(exporter, mux)\n\tif addr != \"\" {\n\t\tm.monitoringServer = &http.Server{\n\t\t\tAddr:        listener.Addr().String(),\n\t\t\tHandler:     mux,\n\t\t\tIdleTimeout: 90 * time.Second, // matches http.DefaultTransport keep-alive timeout\n\t\t\tReadTimeout: 30 * time.Second,\n\t\t}\n\t}\n\n\tversion.Info.RecordComponentBuildTag(\"pilot\")","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/istio/istio/blob/8dc789c5cf17517c64e3c36cb3288230f149dfae/pilot/pkg/bootstrap/monitoring.go#L69-L105","documentation":"startMonitor binds istiod's monitoring HTTP endpoint with net.Listen(\"tcp\", addr) — the addr from --monitoringAddr, default :15014. The listen syscall failed: the address is already in use, invalid, or the port is privileged/unavailable. It propagates up as \"error initializing monitor\" and istiod exits.","triggerScenarios":"Another process (a second istiod/pilot, an agent, a hostPort collision) already holds 15014; --monitoringAddr is malformed; the port is outside the allowed range in the container runtime.","commonSituations":"Duplicate istiod replicas on one node with hostPort 15014; sidecar or node exporters grabbing the port; leftover process from a crashed istiod; typo'd monitoring address flag.","solutions":["Find the occupant on the node: ss -ltnp 'sport = :15014' (or kubectl describe pod to spot hostPort conflicts)","Stop the duplicate process/pod holding the port","Change --monitoringAddr to a free port, or set it empty to multiplex monitoring onto the httpAddr listener (server.go skips a dedicated listener when MonitoringAddr is empty)","Fix a malformed --monitoringAddr value (must be host:port or :port)"],"exampleFix":"# before: port conflict -> \"unable to listen on socket: listen tcp :15014: bind: address already in use\"\nistiod --monitoringAddr=:15014   # another istiod already binds 15014\n\n# after: move monitoring to a free port (or leave empty to share the HTTP listener)\nistiod --monitoringAddr=:15015","handlingStrategy":"validation","validationCode":"// Reserve the monitoring port before istiod starts\nfunc portFree(addr string) bool {\n    ln, err := net.Listen(\"tcp\", addr)\n    if err != nil { return false }\n    _ = ln.Close()\n    return true\n}\nif !portFree(\":15014\") { return errors.New(\"monitoring port busy\") }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid hostPort 15014 when multiple istiod replicas share a node","Set --monitoringAddr to a free port or empty to multiplex on the HTTP listener","Check ss -ltnp for port occupants before restarting istiod"],"tags":["istiod","networking","port","monitoring","startup"],"backgroundTag":null,"analyzedSha":"8dc789c5cf17517c64e3c36cb3288230f149dfae","analyzedAt":"2026-08-15T15:16:55.434Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}