Connection Error

Overview

A network partition, a server that hasn't started yet, or a typo in the address are all normal facts of life in distributed systems — and a client that blocks indefinitely or crashes with an unhandled exception turns a routine outage into a cascading failure. Fail-fast connection checking lets you detect an unreachable KubeMQ server the moment you call ConnectAsync(), bounded by ConnectionTimeout, so your service can log the failure, alert, or fall back instead of hanging.

ConnectAsync() throws a typed KubeMQConnectionException — a subclass of the base KubeMQException — the instant the TCP/gRPC handshake cannot complete, rather than deferring the failure to some later operation. ex.ErrorCode gives you the gRPC status code and ex.IsRetryable tells you whether attempting again is worthwhile, while catching the base KubeMQException also covers authorization and operation failures in the same handler. Gotchas: catch KubeMQConnectionException before the base KubeMQException, or you lose the connection-specific IsRetryable signal; IsRetryable reflects the failure category, not your retry budget — retrying an unreachable server in a tight loop just multiplies the outage; a successful ConnectAsync() doesn't guarantee the connection stays up, so mid-session drops still need reconnection handling.

Prerequisites

• KubeMQ server running on localhost:50000
• C# SDK installed (dotnet add package KubeMQ.SDK.CSharp)

Code

// KubeMQ .NET SDK — ErrorHandling: Connection Error
//
// This example demonstrates handling connection errors when the KubeMQ server
// is unreachable. The SDK throws KubeMQConnectionException on connection failure.
//
// Prerequisites:
//   - Intentionally NO KubeMQ server running on the specified address
//   - dotnet run

using KubeMQ.Sdk.Client;
using KubeMQ.Sdk.Exceptions;

var options = new KubeMQClientOptions
{
    Address = "localhost:59999", // Wrong port — server not listening here
    ClientId = "csharp-errorhandling-connection-error-client",
    ConnectionTimeout = TimeSpan.FromSeconds(5),
};

await using var client = new KubeMQClient(options);

try
{
    Console.WriteLine("Attempting to connect to an unreachable server...");
    await client.ConnectAsync();
    Console.WriteLine("Connected (unexpected).");
}
catch (KubeMQConnectionException ex)
{
    Console.WriteLine($"Connection failed (expected): {ex.Message}");
    Console.WriteLine($"  ErrorCode: {ex.ErrorCode}");
    Console.WriteLine($"  IsRetryable: {ex.IsRetryable}");
}
catch (KubeMQException ex)
{
    Console.WriteLine($"KubeMQ error: {ex.Message}");
    Console.WriteLine($"  Category: {ex.Category}");
}
catch (Exception ex)
{
    Console.WriteLine($"Unexpected error: {ex.GetType().Name} — {ex.Message}");
}

Console.WriteLine("Done.");

How It Works

• ConnectionTimeout = TimeSpan.FromSeconds(5) limits how long ConnectAsync() waits before giving up; the server is intentionally unreachable so the timeout fires quickly.
• The SDK throws KubeMQConnectionException (a subclass of KubeMQException) when the TCP/gRPC handshake cannot complete; ex.ErrorCode gives the gRPC status code and ex.IsRetryable signals whether a retry makes sense.
• Catching the base KubeMQException also handles authorization and operation failures in the same handler.
• Catching bare Exception last ensures any unexpected transport errors are still logged rather than silently swallowed.

Related

• C# SDK Reference
• Graceful Shutdown
• Reconnection