# Command Timeout (/sdks/ruby/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 the calling thread and cascades into upstream timeouts.

The timeout is set per call with `timeout` on `KubeMQ::CQ::CommandMessage`, 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, `send_command` returns a result with a populated `error` instead of a clean reply — your signal to retry or fall back.

**Gotchas:** `timeout` on `CommandMessage` is expressed in **milliseconds**, not seconds, unlike queue wait timeouts — an easy unit mistake; a slow-but-alive handler and a completely absent one produce the *same* timeout error, so you can't tell them apart from the error alone; and setting the timeout too short under normal load turns transient latency into false failures.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Ruby SDK installed (`gem install kubemq`)

## Code [#code]

```ruby title="main.rb"
require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
channel = 'ruby-rpc.command-timeout'

begin
  client = KubeMQ::CQClient.new(address: address, client_id: 'cmd-timeout-example')
  puts "Connected to #{address}"

  puts 'Sending command with short timeout and no handler...'
  msg = KubeMQ::CQ::CommandMessage.new(
    channel: channel,
    timeout: 2,
    metadata: 'will-timeout',
    body: 'no-handler'
  )

  result = client.send_command(msg)
  if result.error.to_s.empty?
    puts "Command response (unexpected): executed=#{result.executed}"
  else
    puts "Command timed out (expected): #{result.error}"
  end
rescue KubeMQ::Error => e
  puts "Command timed out (expected): #{e.message}"
ensure
  client&.close
  puts 'Done'
end
```

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

* When no handler subscribes to the command channel, the sender receives a timeout error.
* The `timeout` value (in milliseconds) determines how long the broker waits for a handler to respond.
* Use appropriate timeouts based on expected handler processing time.
* Review timeouts, channel names, and client IDs before running against shared environments.

## Related [#related]

* [Pattern overview](/learn/rpc/getting-started)
* [Ruby SDK Reference](/sdks/ruby/reference)
* [Send Command](/sdks/ruby/tutorials/command-send)
* [Handle Command](/sdks/ruby/how-to/rpc/command-handle)