{"record":{"id":"0e8278ec4f095288","repo":"microsoft/garnet","slug":"cluster-mode-requires-definition-of-at-least-one-t","errorCode":null,"errorMessage":"Cluster mode requires definition of at least one TCP socket through either the --bind or --cluster-announce-ip options!","messagePattern":"Cluster mode requires definition of at least one TCP socket through either the --bind or --cluster-announce-ip options!","errorType":"exception","errorClass":"GarnetException","httpStatus":null,"severity":"critical","filePath":"libs/server/StoreWrapper.cs","lineNumber":354,"sourceCode":"            {\n                foreach (var server in servers)\n                {\n                    if (server is GarnetServerTcp tcpServer && tcpServer.EndPoint is IPEndPoint point)\n                    {\n                        localEndPoint = point;\n                        break;\n                    }\n                }\n            }\n            else\n            {\n                if (serverOptions.ClusterAnnounceEndpoint is IPEndPoint point)\n                    localEndPoint = point;\n            }\n\n            // Fail if we cannot advertise an endpoint for remote nodes to connect to\n            if (localEndPoint == null)\n                throw new GarnetException(\"Cluster mode requires definition of at least one TCP socket through either the --bind or --cluster-announce-ip options!\");\n\n            if (localEndPoint.Address.Equals(IPAddress.Any))\n            {\n                using (Socket socket = new(AddressFamily.InterNetwork, SocketType.Dgram, 0))\n                {\n                    socket.Connect(\"8.8.8.8\", 65530);\n                    var endPoint = socket.LocalEndPoint as IPEndPoint;\n                    return new IPEndPoint(endPoint.Address, localEndPoint.Port);\n                }\n            }\n            else if (localEndPoint.Address.Equals(IPAddress.IPv6Any))\n            {\n                using (Socket socket = new(AddressFamily.InterNetworkV6, SocketType.Dgram, 0))\n                {\n                    socket.Connect(\"2001:4860:4860::8888\", 65530);\n                    var endPoint = socket.LocalEndPoint as IPEndPoint;\n                    return new IPEndPoint(endPoint.Address, localEndPoint.Port);\n                }","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/microsoft/garnet/blob/951b0fc6838721f89d102c2bbe1b914e8d39d700/libs/server/StoreWrapper.cs#L336-L372","documentation":"In cluster mode, Garnet must advertise a network endpoint so other cluster nodes can connect. StoreWrapper resolves the local endpoint from --bind or --cluster-announce-ip. If neither yields an IPEndPoint, the server throws at startup. This prevents a cluster node from booting without a reachable address, which would make it invisible to peers.","triggerScenarios":"Starting the server with --cluster enabled but neither --bind nor --cluster-announce-ip specifying a TCP endpoint. For example, running 'garnet-server --cluster' with no bind address, or setting --cluster-announce-ip to a hostname that does not resolve to an IPEndPoint.","commonSituations":"First-time cluster setup forgetting to add --bind; Docker/container deployments where --bind was set to a hostname rather than an IP; Kubernetes pods where the announce IP environment variable is unset; misconfigured cluster-announce-port without a matching IP.","solutions":["Add --bind <ip>:<port> (e.g., --bind 0.0.0.0:6379) to the server startup flags.","Set --cluster-announce-ip <ip> and --cluster-announce-port <port> if the bind address differs from the externally visible address.","In Docker/Kubernetes, set --cluster-announce-ip to the pod/service IP and ensure the port is exposed."],"exampleFix":"// before\ngarnet-server --cluster\n\n// after\ngarnet-server --cluster --bind 0.0.0.0:6379","handlingStrategy":"validation","validationCode":"// Validate cluster endpoint before startup\nif (options.EnableCluster)\n{\n    if (string.IsNullOrEmpty(options.BindAddress) && string.IsNullOrEmpty(options.ClusterAnnounceIp))\n        throw new InvalidOperationException(\"Cluster mode requires --bind or --cluster-announce-ip.\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always specify --bind when enabling cluster mode.","In containerized deployments, set --cluster-announce-ip to the externally reachable IP.","Validate the endpoint resolves to a concrete IPEndPoint in a startup check."],"tags":["cluster","configuration","startup","network","garnet"],"backgroundTag":null,"analyzedSha":"951b0fc6838721f89d102c2bbe1b914e8d39d700","analyzedAt":"2026-08-13T19:01:32.939Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}