{"record":{"id":"2411831dfd8dc1c2","repo":"nsqio/nsq","slug":"listen-s-failed-s-241183","errorCode":null,"errorMessage":"listen (%s) failed - %s","messagePattern":"listen \\((.+?)\\) failed - (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nsqd/nsqd.go","lineNumber":154,"sourceCode":"\tn.clientTLSConfig = clientTLSConfig\n\n\tif opts.AuthHTTPRequestMethod != \"post\" && opts.AuthHTTPRequestMethod != \"get\" {\n\t\treturn nil, errors.New(\"--auth-http-request-method must be post or get\")\n\t}\n\n\tfor _, v := range opts.E2EProcessingLatencyPercentiles {\n\t\tif v <= 0 || v > 1 {\n\t\t\treturn nil, fmt.Errorf(\"invalid E2E processing latency percentile: %v\", v)\n\t\t}\n\t}\n\n\tn.logf(LOG_INFO, version.String(\"nsqd\"))\n\tn.logf(LOG_INFO, \"ID: %d\", opts.ID)\n\n\tn.tcpServer = &tcpServer{nsqd: n}\n\tn.tcpListener, err = net.Listen(util.TypeOfAddr(opts.TCPAddress), opts.TCPAddress)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"listen (%s) failed - %s\", opts.TCPAddress, err)\n\t}\n\tif opts.HTTPAddress != \"\" {\n\t\tn.httpListener, err = net.Listen(util.TypeOfAddr(opts.HTTPAddress), opts.HTTPAddress)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"listen (%s) failed - %s\", opts.HTTPAddress, err)\n\t\t}\n\t}\n\tif n.tlsConfig != nil && opts.HTTPSAddress != \"\" {\n\t\tn.httpsListener, err = tls.Listen(\"tcp\", opts.HTTPSAddress, n.tlsConfig)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"listen (%s) failed - %s\", opts.HTTPSAddress, err)\n\t\t}\n\t}\n\tif opts.BroadcastHTTPPort == 0 {\n\t\ttcpAddr, ok := n.RealHTTPAddr().(*net.TCPAddr)\n\t\tif ok {\n\t\t\topts.BroadcastHTTPPort = tcpAddr.Port\n\t\t}","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/nsqio/nsq/blob/85cf10c09c6c3c86160d6f0eb156f62d0efc1648/nsqd/nsqd.go#L136-L172","documentation":"nsqd failed to bind its TCP listener (net.Listen on opts.TCPAddress, default 0.0.0.0:4150, flag --tcp-address). This is the NSQ protocol V2 socket that producers and consumers connect to. New() wraps the underlying net.Listen error (address in use, permission denied, invalid address, DNS failure) with the requested address, so the cause is visible after the dash.","triggerScenarios":"Another nsqd (or any process) already bound 4150; binding a privileged port (<1024) as non-root; passing a malformed address like '4150' or 'tcp://0.0.0.0:4150' (must be host:port); --tcp-address=0.0.0.0:4150 inside a container where the port is already forwarded; net.Listen with a network type derived via util.TypeOfAddr that does not match the string.","commonSituations":"Running a second nsqd instance with default flags on the same host; a crashed nsqd whose socket lingers briefly (TIME_WAIT/backlog); systemd/docker restart races; typo'd --tcp-address in a supervisor config; running as an unprivileged user after someone changed the port to 72.","solutions":["Find and stop the current holder: `ss -ltnp 'sport = :4150'` or `lsof -iTCP:4150 -sTCP:LISTEN`, then kill it or wait for it to exit.","If two nsqd nodes must coexist, give each its own port: --tcp-address=0.0.0.0:4152 (plus matching --http-address/--https-address).","Verify the address format is host:port (e.g. 0.0.0.0:4150 or 127.0.0.1:4150) with no scheme prefix.","For privileged ports, pick >=1024 or run under setcap/systemd socket activation."],"exampleFix":"# before\nnsqd  # second instance, default 0.0.0.0:4150 already taken\n\n# after\nnsqd --tcp-address=0.0.0.0:4152 --http-address=0.0.0.0:4153","handlingStrategy":"validation","validationCode":"// Go: probe the port before starting nsqd\nif ln, err := net.Listen(\"tcp\", opts.TCPAddress); err != nil {\n    return fmt.Errorf(\"tcp address %s unavailable: %w\", opts.TCPAddress, err)\n} else { ln.Close() }","typeGuard":null,"tryCatchPattern":"if n, err := nsqd.New(opts); err != nil {\n    if strings.Contains(err.Error(), \"listen (\") {\n        // inspect wrapped cause: address in use / permission / bad address\n    }\n    return err\n}","preventionTips":["One process per (host, port); script startup checks with `ss -ltnp` before launch.","Always give co-located nsqd nodes distinct --tcp-address/--http-address/--https-address.","Prefer address 127.0.0.1:port for single-machine setups to dodge wildcard collisions."],"tags":["nsqd","network","listen","port-in-use","startup","tcp"],"backgroundTag":null,"analyzedSha":"85cf10c09c6c3c86160d6f0eb156f62d0efc1648","analyzedAt":"2026-08-16T00:53:05.009Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}