# Reconnection (/sdks/ruby/how-to/error-handling/reconnection)



## Overview [#overview]

Production connections drop for reasons that have nothing to do with your application code: the broker restarts during a rolling upgrade, a load balancer fails over, a network blip severs the connection. Without built-in reconnection, every client in your fleet needs its own hand-rolled retry-connect loop, and it's easy to get the backoff wrong — too aggressive and you hammer a recovering broker, too slow and you leave the application dark longer than necessary. Automatic reconnection moves that logic into the client itself, so the connection self-heals without any code the application has to write or maintain.

It works by passing a `KubeMQ::ReconnectPolicy` to the client — `base_interval`, `max_delay`, and `max_attempts` shape the backoff curve, with a default of 1–30 second delays, a 2x multiplier, and 25% jitter to avoid a thundering herd when many clients reconnect at once. Once reconnected, subscriptions automatically resume from their last received position, so no manual re-subscribe logic is needed. **Gotchas:** the default policy retries unlimited attempts, so a broker that's gone for good will be retried forever unless you set `max_attempts` explicitly; in-flight `send_event` calls made during the outage window still raise immediately — the policy governs the *connection*, not individual sends; and jitter means retry timing isn't perfectly predictable, which is intentional but can complicate log correlation across a fleet of reconnecting clients.

## 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')

begin
  client = KubeMQ::PubSubClient.new(
    address: address,
    client_id: 'reconnect-example',
    reconnect_policy: KubeMQ::ReconnectPolicy.new(base_interval: 2.0)
  )
  puts "Connected to #{address}"

  info = client.ping
  puts "Ping OK: host=#{info.host}, version=#{info.version}"

  channel = 'ruby-error-handling.reconnection'
  3.times do |i|
    msg = KubeMQ::PubSub::EventMessage.new(channel: channel, metadata: "heartbeat-#{i}", body: "data-#{i}")
    client.send_event(msg)
    puts "Sent heartbeat #{i}"
    sleep 1
  end
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Done'
end
```

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

* The SDK's `ReconnectPolicy` automatically reconnects with exponential backoff and jitter.
* Default settings: 1–30 second backoff, 2x multiplier, 25% jitter, unlimited attempts.
* Subscriptions auto-resume from the last received position after reconnection.
* Customize via `KubeMQ::ReconnectPolicy.new(base_interval:, max_delay:, max_attempts:)`.
* Review timeouts, channel names, and client IDs before running against shared environments.

## Related [#related]

* [Ruby SDK Reference](/sdks/ruby/reference)
* [Custom Timeouts](/sdks/ruby/how-to/connection/custom-timeouts)
* [Connection Error](/sdks/ruby/how-to/error-handling/connection-error)