# Connection Error (/sdks/go/how-to/error-handling/connection-error)



## Overview [#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 panics on connect turns a routine outage into a cascading failure. **Fail-fast connection checking** lets you detect an unreachable KubeMQ server the moment you construct the client, with a bounded wait, so your service can log the failure, alert, or fall back instead of hanging.

`kubemq.WithCheckConnection(true)` makes `NewClient` perform a synchronous connectivity check during construction, paired with `WithConnectionTimeout` to cap how long that check waits before giving up and returning an error. Without it, `NewClient` succeeds unconditionally and any connection problem only surfaces later, on the first real operation. **Gotchas:** skip `WithCheckConnection` and a dead server looks identical to a healthy one until you try to use it — silent until it isn't; set the timeout too short and a merely slow (but healthy) server gets misreported as unreachable; a successful `NewClient` doesn't guarantee the connection stays up, so you still need reconnection handling for failures that happen mid-session.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Go SDK installed (`go get github.com/kubemq-io/kubemq-go/v2`)

## Code [#code]

```go title="main.go"
// Example: error-handling/connection-error
//
// Demonstrates handling connection errors when the KubeMQ server is
// unreachable. Shows how to use WithCheckConnection to fail fast on
// startup, and how to handle connection failures gracefully.
//
// Channel: go-error-handling.connection-error
// Client ID: go-error-handling-connection-error-client
//
// This example intentionally connects to a non-existent server.
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kubemq-io/kubemq-go/v2"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Attempt to connect to a non-existent server with CheckConnection enabled.
	// This causes NewClient to fail fast if the server is unreachable.
	client, err := kubemq.NewClient(ctx,
		kubemq.WithAddress("localhost", 59999), // Non-existent server
		kubemq.WithClientId("go-error-handling-connection-error-client"),
		kubemq.WithCheckConnection(true),
		kubemq.WithConnectionTimeout(3*time.Second),
	)
	if err != nil {
		fmt.Printf("Connection failed (expected): %v\n", err)
		fmt.Println("Tip: Use WithCheckConnection(true) to detect unreachable servers at startup")
		return
	}
	defer client.Close()

	// If we get here, verify with a ping.
	info, err := client.Ping(ctx)
	if err != nil {
		log.Printf("Ping failed: %v", err)
		return
	}
	fmt.Printf("Connected: %s\n", info.Host)
}

```

## How It Works [#how-it-works]

1. `kubemq.WithCheckConnection(true)` makes `NewClient` perform a synchronous connectivity check during construction and return an error immediately if the server is unreachable, rather than deferring errors to the first operation.
2. `WithConnectionTimeout(3 * time.Second)` caps how long the initial dial attempt waits before giving up.
3. Connecting to port `59999` intentionally triggers the error path so the example can demonstrate the failure message and the `WithCheckConnection` tip.
4. Without `WithCheckConnection`, the client constructor succeeds even when the server is down; failures would surface on the first actual operation instead.

## Related [#related]

* [Go SDK Reference](/sdks/go/reference)
* [Graceful Shutdown](/sdks/go/how-to/error-handling/graceful-shutdown)
* [Reconnection](/sdks/go/how-to/error-handling/reconnection)