# Connection Error (/sdks/cpp/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 crashes turns a routine outage into a cascading failure. **Fail-fast connection checking** lets you detect an unreachable KubeMQ server the moment you call `Client::Create`, so your service can log the failure, alert, or fall back instead of hanging.

`options.set_check_connection(true)` makes `Client::Create` perform a synchronous connectivity check during construction, paired with `set_connection_timeout` to cap how long that check waits before giving up and returning a non-OK `Status`. Without it, `Create` succeeds unconditionally and any connection problem only surfaces later, on the first real RPC. **Gotchas:** skip `set_check_connection` 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; every `Status`-returning call — including `Close()` — should be checked, since a successful `Create` doesn't guarantee the connection stays up for the lifetime of the client.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* C++ SDK installed (vcpkg or CMake FetchContent)
* C++17 compiler (GCC 9+, Clang 9+, MSVC 2019+)

## Code [#code]

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

#include <kubemq/kubemq.h>

#include <chrono>
#include <iostream>

int main() {
    std::cout << "[1] Attempting connection to non-existent server localhost:59999" << std::endl;

    // Configure client to connect to a non-existent server with
    // check_connection enabled. This causes Create to fail fast
    // if the server is unreachable.
    kubemq::ClientOptions options;
    options.set_address("localhost", 59999);
    options.set_client_id("cpp-error-handling-connection-error-client");
    options.set_check_connection(true);
    options.set_connection_timeout(std::chrono::seconds(3));

    auto client_result = kubemq::Client::Create(options);
    if (!client_result.ok()) {
        std::cout << "[2] Connection failed (expected): " << client_result.status().message()
                  << std::endl;
        std::cout << "[3] Tip: Use set_check_connection(true) to detect "
                  << "unreachable servers at startup" << std::endl;
        return 0;
    }
    auto& client = *client_result;

    // If we get here unexpectedly, verify with a ping.
    auto ping_result = client->Ping();
    if (!ping_result.ok()) {
        std::cerr << "[ERROR] Ping failed: " << ping_result.status().message() << std::endl;
        auto close_status = client->Close();
        if (!close_status.ok()) {
            std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
        }
        return 1;
    }
    std::cout << "[2] Connected (unexpected): host=" << ping_result->host << std::endl;

    // Close the client explicitly.
    // Note: The Client destructor also calls Close(), but explicit
    // cleanup is shown here for clarity and to match Go's defer pattern.
    auto close_status = client->Close();
    if (!close_status.ok()) {
        std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
        return 1;
    }

    return 0;
}
```

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

* Attempts to connect to a non-existent server on port 59999.
* Uses `set_check_connection(true)` to fail fast if the server is unreachable.
* Sets a short connection timeout (3s) to avoid long waits.
* The `Create()` call returns an error Status with a descriptive message.

## Related [#related]

* [C++ SDK Reference](/sdks/cpp/reference/types-and-errors)
* [Reconnection](/sdks/cpp/how-to/error-handling/reconnection)
* [Graceful Shutdown](/sdks/cpp/how-to/error-handling/graceful-shutdown)