{"record":{"id":"73d8a4b8fabfabdd","repo":"nats-io/nats-server","slug":"can-t-listen-to-the-monitor-port-v","errorCode":null,"errorMessage":"can't listen to the monitor port: %v","messagePattern":"can't listen to the monitor port: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/server.go","lineNumber":3140,"sourceCode":"\t\thp = net.JoinHostPort(opts.HTTPHost, strconv.Itoa(port))\n\t\tconfig := opts.TLSConfig.Clone()\n\t\tif !s.ocspPeerVerify {\n\t\t\tconfig.GetConfigForClient = s.getMonitoringTLSConfig\n\t\t\tconfig.ClientAuth = tls.NoClientCert\n\t\t}\n\t\thttpListener, err = tls.Listen(\"tcp\", hp, config)\n\n\t} else {\n\t\tport = opts.HTTPPort\n\t\tif port == -1 {\n\t\t\tport = 0\n\t\t}\n\t\thp = net.JoinHostPort(opts.HTTPHost, strconv.Itoa(port))\n\t\thttpListener, err = net.Listen(\"tcp\", hp)\n\t}\n\n\tif err != nil {\n\t\treturn fmt.Errorf(\"can't listen to the monitor port: %v\", err)\n\t}\n\n\trport := httpListener.Addr().(*net.TCPAddr).Port\n\ts.Noticef(\"Starting %s monitor on %s\", monitorProtocol, net.JoinHostPort(opts.HTTPHost, strconv.Itoa(rport)))\n\n\tmux := http.NewServeMux()\n\n\t// Root\n\tmux.HandleFunc(s.basePath(RootPath), s.HandleRoot)\n\t// Varz\n\tmux.HandleFunc(s.basePath(VarzPath), s.HandleVarz)\n\t// Connz\n\tmux.HandleFunc(s.basePath(ConnzPath), s.HandleConnz)\n\t// Routez\n\tmux.HandleFunc(s.basePath(RoutezPath), s.HandleRoutez)\n\t// Gatewayz\n\tmux.HandleFunc(s.basePath(GatewayzPath), s.HandleGatewayz)\n\t// Leafz","sourceCodeStart":3122,"sourceCodeEnd":3158,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/server.go#L3122-L3158","documentation":"The monitoring listener could not be bound: net.Listen(\"tcp\", host:port) failed and the underlying OS error is wrapped. Typical causes are the port already in use, permission denied for privileged ports, or an unbindable host address.","triggerScenarios":"startMonitoring calls net.Listen for opts.HTTPPort/HTTPSPort (or the randomly allocated port) on opts.HTTPHost; any listen error (EADDRINUSE, EACCES, invalid host) triggers this.","commonSituations":"Another nats-server or old instance still holding 8222; binding to a hostname that doesn't resolve to a local interface; port <1024 without root; container missing CAP_NET_BIND_SERVICE.","solutions":["Check and free the port: `lsof -i :8222` / `ss -ltnp`, stop the conflicting process or pick another port","Bind to 0.0.0.0 or the loopback interface instead of an unresolvable host in `http_host`","For ports <1024 run with the required capability/root or choose a high port","Read the wrapped `%v` OS error to distinguish address-in-use vs permission vs no-route"],"exampleFix":"// before\nhttp_host: \"myhost.internal\"\nhttp_port: 8222\n// after\nhttp_host: \"0.0.0.0\"\nhttp_port: 8222","handlingStrategy":"validation","validationCode":"// Pre-check that the monitor port is bindable before starting the server\nfunc portFree(host string, port int) error {\n    ln, err := net.Listen(\"tcp\", net.JoinHostPort(host, strconv.Itoa(port)))\n    if err != nil { return err }\n    return ln.Close()\n}","typeGuard":null,"tryCatchPattern":"if err := srv.StartMonitoring(); err != nil {\n    var wrapped string = err.Error()\n    if strings.Contains(wrapped, \"can't listen to the monitor port\") {\n        if strings.Contains(wrapped, \"address already in use\") {\n            log.Print(\"monitor port taken: stop the other process or change http_port\")\n        } else if strings.Contains(wrapped, \"permission denied\") {\n            log.Print(\"use a port >1024 or grant CAP_NET_BIND_SERVICE\")\n        }\n    }\n    return err\n}","preventionTips":["Prefer high ports (>1024) for monitoring to avoid permission issues","Use http_host: 0.0.0.0 or a concrete local IP, not an external hostname","Check for lingering instances with `ss -ltnp | grep 8222` before restarts","In containers, ensure the port isn't claimed by a sidecar or previous run"],"tags":["nats-server","monitoring","network","port-in-use"],"backgroundTag":"address-already-in-use","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}