microsoft/garnet · critical · GarnetException

Cluster mode requires definition of at least one TCP socket

Error message

Cluster mode requires definition of at least one TCP socket through either the --bind or --cluster-announce-ip options!

What it means

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.

Source

Thrown at libs/server/StoreWrapper.cs:354

            {
                foreach (var server in servers)
                {
                    if (server is GarnetServerTcp tcpServer && tcpServer.EndPoint is IPEndPoint point)
                    {
                        localEndPoint = point;
                        break;
                    }
                }
            }
            else
            {
                if (serverOptions.ClusterAnnounceEndpoint is IPEndPoint point)
                    localEndPoint = point;
            }

            // Fail if we cannot advertise an endpoint for remote nodes to connect to
            if (localEndPoint == null)
                throw new GarnetException("Cluster mode requires definition of at least one TCP socket through either the --bind or --cluster-announce-ip options!");

            if (localEndPoint.Address.Equals(IPAddress.Any))
            {
                using (Socket socket = new(AddressFamily.InterNetwork, SocketType.Dgram, 0))
                {
                    socket.Connect("8.8.8.8", 65530);
                    var endPoint = socket.LocalEndPoint as IPEndPoint;
                    return new IPEndPoint(endPoint.Address, localEndPoint.Port);
                }
            }
            else if (localEndPoint.Address.Equals(IPAddress.IPv6Any))
            {
                using (Socket socket = new(AddressFamily.InterNetworkV6, SocketType.Dgram, 0))
                {
                    socket.Connect("2001:4860:4860::8888", 65530);
                    var endPoint = socket.LocalEndPoint as IPEndPoint;
                    return new IPEndPoint(endPoint.Address, localEndPoint.Port);
                }

View on GitHub (pinned to 951b0fc683)

Solutions

1. Add --bind <ip>:<port> (e.g., --bind 0.0.0.0:6379) to the server startup flags.
2. Set --cluster-announce-ip <ip> and --cluster-announce-port <port> if the bind address differs from the externally visible address.
3. In Docker/Kubernetes, set --cluster-announce-ip to the pod/service IP and ensure the port is exposed.

Example fix

// before
garnet-server --cluster

// after
garnet-server --cluster --bind 0.0.0.0:6379

// Validate cluster endpoint before startup
if (options.EnableCluster)
{
    if (string.IsNullOrEmpty(options.BindAddress) && string.IsNullOrEmpty(options.ClusterAnnounceIp))
        throw new InvalidOperationException("Cluster mode requires --bind or --cluster-announce-ip.");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot use null device for AOF when cluster is enabled and y
• AofMemorySize (effective {effectiveMemory} after rounding do
• AofPageSize (effective {effectivePage} after rounding down t
• AofPageSize (effective {effectiveAofPage} after rounding dow
• {propName} '{value}' (effective {adjustedSize} bytes after r

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/0e8278ec4f095288. Report an issue: GitHub.