microsoft/garnet · error · Exception

Failed to connect at {endpoint}

Error message

Failed to connect at {endpoint}

What it means

Thrown by LightClient.ConnectSendSocket when no socket connection to the target endpoint can be established. It is the terminal failure after all connection attempts (DNS-resolved addresses or a direct endpoint) have been tried and none succeeded.

Source

Thrown at libs/common/LightClient.cs:161

                        NoDelay = true
                    };

                    if (TryConnectSocket(socket, endpoint))
                        return socket;
                }
            }
            else
            {
                var socket = new Socket(endpoint.AddressFamily, SocketType.Stream, ProtocolType.Unspecified);
                if (endpoint is not UnixDomainSocketEndPoint)
                    socket.NoDelay = true;

                if (TryConnectSocket(socket, endpoint))
                    return socket;
            }

            logger?.LogWarning("Failed to connect at {endpoint}", endpoint);
            throw new Exception($"Failed to connect at {endpoint}");
        }

        /// <inheritdoc cref="ConnectSendSocket"/>
        private async Task<Socket> ConnectSendSocketAsync(CancellationToken cancellationToken = default)
        {
            if (endpoint is DnsEndPoint dnsEndpoint)
            {
                var hostEntries = await Dns.GetHostEntryAsync(dnsEndpoint.Host, cancellationToken).ConfigureAwait(false);
                // Try all available DNS entries if a hostName is provided
                foreach (var addressEntry in hostEntries.AddressList)
                {
                    var endpoint = new IPEndPoint(addressEntry, dnsEndpoint.Port);
                    var socket = new Socket(endpoint.AddressFamily, SocketType.Stream, ProtocolType.Tcp)
                    {
                        NoDelay = true
                    };

                    if (await TryConnectSocketAsync(socket, endpoint, cancellationToken).ConfigureAwait(false))

View on GitHub (pinned to 951b0fc683)

Solutions

1. Verify the target endpoint is reachable and the server is listening (e.g. telnet/netcat to host:port).
2. Check the configured host/port or Unix socket path for typos.
3. Inspect network/firewall rules between client and target, then retry with backoff.
4. For DNS endpoints, confirm resolution returns live addresses.

Example fix

// before
var socket = LightClient.ConnectSendSocket(endpoint);
// after
if (!LightClient.CanConnect(endpoint, timeout: TimeSpan.FromSeconds(2)))
    throw new InvalidOperationException($"Target not reachable: {endpoint}");
var socket = LightClient.ConnectSendSocket(endpoint);

// Probe reachability before attempting the blocking connect
using var probe = new Socket(endpoint.AddressFamily, SocketType.Stream, ProtocolType.Unspecified);
var connected = probe.BeginConnect(endpoint, null, null);
if (!connected.AsyncWaitHandle.WaitOne(TimeSpan.FromSeconds(2)) || !probe.Connected)
    throw new InvalidOperationException($"Target not reachable: {endpoint}");

for (int attempt = 0; attempt < maxAttempts; attempt++)
{
    try { return LightClient.ConnectSendSocket(endpoint); }
    catch (Exception ex) when (ex.Message.StartsWith("Failed to connect at"))
    {
        logger?.LogWarning("Connect attempt {n}/{max} to {endpoint} failed: {msg}", attempt + 1, maxAttempts, endpoint, ex.Message);
        if (attempt == maxAttempts - 1) throw;
        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), ct);
    }
}
throw new Exception("unreachable");

When it happens

Trigger: All TCP/Unix-domain socket connect attempts to endpoint fail: connection refused, host unreachable, DNS resolves but no port listening, or timeout in TryConnectSocket.

Common situations: Target node down or not started; wrong host/port in config; firewall/network partition; Unix-domain socket path missing or wrong; peer overloaded and refusing connections.

Related errors

• Need to provide SslClientAuthenticationOptions when TLS is e
• Cannot provide SslClientAuthenticationOptions when TLS is di
• Disconnected
• Failed to connect at {EndPoint}
• Failed to connect at {EndPoint}

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