Connection Error
Detect and handle KubeMQ connection failures gracefully in the C++ SDK with proper error reporting and recovery.
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
- KubeMQ server running on
localhost:50000 - C++ SDK installed (vcpkg or CMake FetchContent)
- C++17 compiler (GCC 9+, Clang 9+, MSVC 2019+)
Code
// 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
- 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
Was this page helpful?