{"record":{"id":"5ab54f45fb6e77d1","repo":"hashicorp/nomad","slug":"failed-to-start-http-listener-v","errorCode":null,"errorMessage":"failed to start HTTP listener: %v","messagePattern":"failed to start HTTP listener: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"command/agent/http.go","lineNumber":192,"sourceCode":"\t// Enable HTTP2 unless it has been disabled in the configuration.\n\tif !config.HTTPDisableHTTP2 {\n\t\tprotocols.SetHTTP2(true)\n\t\t// If TLS is not enabled for HTTP, make HTTP2 available over cleartext.\n\t\tif !config.TLSConfig.EnableHTTP {\n\t\t\tprotocols.SetUnencryptedHTTP2(true)\n\t\t}\n\t}\n\n\t// Start the listener\n\tfor _, addr := range config.normalizedAddrs.HTTP {\n\t\tlnAddr, err := net.ResolveTCPAddr(\"tcp\", addr)\n\t\tif err != nil {\n\t\t\tserverInitializationErrors = multierror.Append(serverInitializationErrors, err)\n\t\t\tcontinue\n\t\t}\n\t\tln, err := config.Listener(\"tcp\", lnAddr.IP.String(), lnAddr.Port)\n\t\tif err != nil {\n\t\t\tserverInitializationErrors = multierror.Append(serverInitializationErrors, fmt.Errorf(\"failed to start HTTP listener: %v\", err))\n\t\t\tcontinue\n\t\t}\n\n\t\t// If TLS is enabled, wrap the listener with a TLS listener\n\t\tif config.TLSConfig.EnableHTTP {\n\t\t\ttlsConfig, err := tlsConf.IncomingTLSConfig()\n\t\t\tif err != nil {\n\t\t\t\tserverInitializationErrors = multierror.Append(serverInitializationErrors, err)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif !config.HTTPDisableHTTP2 {\n\t\t\t\ttlsConfig.NextProtos = []string{ProtoHttp2}\n\t\t\t}\n\t\t\tln = tls.NewListener(tcpKeepAliveListener{ln.(*net.TCPListener)}, tlsConfig)\n\t\t}\n\n\t\t// Create the server\n\t\tsrv := &HTTPServer{","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/http.go#L174-L210","documentation":"Returned by NewHTTPServers (command/agent/http.go:192) when config.Listener fails to open a TCP listener for one of the agent's HTTP addresses. The error is appended to a multierror and that listener skipped; startup fails only if no listener can be created.","triggerScenarios":"Binding a port already in use by another process or agent, binding to an IP not present on the host, lacking privilege for ports <1024, or bad address syntax in bind_addr/ports during start or HTTP reload.","commonSituations":"Two agents on one host; a crashed leftover process holding 4646; containers sharing host networking; bind address changed to an IP that no longer exists; SELinux/AppArmor blocking bind.","solutions":["Find and stop the conflicting process (lsof -i :4646 / ss -ltnp) or change `ports { http = ... }` to a free port.","Ensure the configured bind address exists on the host interface.","Use a non-privileged port or grant the required capability for ports <1024.","If it occurred during reload, verify addresses in the new config and reload again."],"exampleFix":"// before (HCL)\nports {\n  http = 4646\n}\n// after (move off the occupied port)\nports {\n  http = 14646\n}","handlingStrategy":"try-catch","validationCode":"addr := &net.TCPAddr{IP: net.ParseIP(bindIP), Port: httpPort}\nln, err := net.Listen(\"tcp\", addr.String())\nif err != nil {\n    return fmt.Errorf(\"http port %d unavailable: %v\", httpPort, err)\n}\nln.Close()","typeGuard":null,"tryCatchPattern":"if err := agent.Setup(); err != nil {\n    if strings.Contains(err.Error(), \"failed to start HTTP listener\") {\n        // check lsof -i :4646 for a conflicting process, change ports, retry\n    }\n}","preventionTips":["Check port availability before starting agents (lsof/ss).","Use distinct ports per agent or rely on defaults.","Ensure bind_addr refers to an IP present on the host.","Clean up crashed agents that hold ports."],"tags":["network","tcp-listener","port-in-use","nomad"],"backgroundTag":"port-already-in-use","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}