# Command Timeout (/sdks/cpp/how-to/rpc/command-timeout)



## Overview [#overview]

A **command timeout** is the deadline you attach to a single RPC call so a caller never blocks forever waiting on a handler that isn't there or isn't responding. Commands are synchronous by design — the sender is parked until a reply arrives — so without a bound, a missing subscriber or a crashed handler turns one request into an indefinite hang that ties up a thread and cascades into upstream timeouts.

The timeout is set per call with `SetTimeout` on `kubemq::Command::Builder`, and it's enforced by the broker itself, not by client-side polling: the broker tracks the deadline server-side and fails the request the moment it expires, regardless of what the calling thread is doing. When the window elapses with no response, `SendCommand` returns a non-OK status carrying timeout information — your signal to retry or fall back.

**Gotchas:** a command timeout is a broker-enforced deadline, not a local socket or connection timeout, so don't assume a connection-level failure implies the broker also gave up on the request; a slow-but-alive handler and a completely absent one produce the *same* non-OK status, so you can't tell them apart from the status alone; and setting the timeout too short under normal load turns transient latency into false failures.

## 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: commands/command_timeout
//
// Demonstrates command timeout handling. When no handler responds
// within the timeout period, the SendCommand call returns an error.
//
// Channel: cpp-commands.command-timeout
// Client ID: cpp-commands-command-timeout-client
//
// Run with a KubeMQ server on localhost:50000
// (see https://docs.kubemq.io/deploy).

#include <kubemq/kubemq.h>

#include <chrono>
#include <iostream>

int main() {
    std::cout << "[1] Connecting to localhost:50000" << std::endl;

    kubemq::ClientOptions options;
    options.set_address("localhost", 50000);
    options.set_client_id("cpp-commands-command-timeout-client");

    auto client_result = kubemq::Client::Create(options);
    if (!client_result.ok()) {
        std::cerr << "[ERROR] Failed to create client: " << client_result.status().message()
                  << std::endl;
        return 1;
    }
    auto& client = *client_result;

    // Send a command to a channel with no handler -- it will timeout.
    std::cout << "[2] Sending command to channel with no handler (2s timeout)" << std::endl;
    auto cmd_result = kubemq::Command::Builder()
                          .SetChannel("cpp-commands.command-timeout")
                          .SetBody("will timeout")
                          .SetTimeout(std::chrono::seconds(2))
                          .Build();
    if (!cmd_result.ok()) {
        std::cerr << "[ERROR] Build command: " << cmd_result.status().message() << std::endl;
        return 1;
    }

    auto resp_result = client->SendCommand(*cmd_result);
    if (!resp_result.ok()) {
        std::cout << "[3] Command timed out as expected: " << resp_result.status().message()
                  << std::endl;
    } else {
        std::cout << "[3] Unexpected: command succeeded without a handler" << 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;
    }
    std::cout << "[4] Client closed" << std::endl;

    return 0;
}
```

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

* Sends a command to a channel with no active handler.
* The `SendCommand()` call returns an error after the specified timeout (2 seconds).
* The error status contains timeout information for appropriate handling.
* Demonstrates defensive programming with proper timeout configuration.

## Related [#related]

* [Pattern overview](/learn/rpc/getting-started)
* [C++ SDK Reference](/sdks/cpp/reference/rpc)
* [Send Command](/sdks/cpp/tutorials/command-send)
* [Connection Error](/sdks/cpp/how-to/error-handling/connection-error)