Connection Error

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 start_link/1, so your service can log the failure, alert, or fall back instead of hanging.

KubeMQ.Client.start_link/1 returns {:error, reason} immediately when the server is unreachable, instead of blocking or crashing the calling process. A guard clause like when is_exception(err) distinguishes a structured KubeMQ error — carrying code, message, and operation — from an arbitrary term returned as reason, so your case can pattern-match precisely on the failure shape. Gotchas: always match both the structured-exception clause and a catch-all {:error, reason} clause, since not every failure reason is a KubeMQ exception struct; a successful start_link/1 doesn't guarantee the connection stays healthy, so mid-session drops still need reconnection handling; validation errors (like an empty channel) surface the same way as connection errors — inspect code before assuming a failed operation means the server is down.

Prerequisites

• Elixir SDK installed ({:kubemq, "~> 1.0"} in mix.exs)

Code

IO.puts("Attempting connection to unreachable server...")

case KubeMQ.Client.start_link(
       address: "localhost:99999",
       client_id: "elixir-error-example"
     ) do
  {:ok, client} ->
    IO.puts("Connected (unexpected for this demo)")
    KubeMQ.Client.close(client)

  {:error, err} when is_exception(err) ->
    IO.puts("KubeMQ error caught:")
    IO.puts("  Code: #{Map.get(err, :code)}")
    IO.puts("  Message: #{Exception.message(err)}")
    IO.puts("  Operation: #{Map.get(err, :operation)}")

  {:error, reason} ->
    IO.puts("Connection error: #{inspect(reason)}")
end

IO.puts("\nAttempting operation on a valid connection with bad channel...")

case KubeMQ.Client.start_link(
       address: "localhost:50000",
       client_id: "elixir-error-example-2"
     ) do
  {:ok, client} ->
    bad_event = %KubeMQ.Event{channel: "", body: "test"}

    case KubeMQ.Client.send_event(client, bad_event) do
      :ok -> IO.puts("Sent (unexpected)")
      {:error, err} -> IO.puts("Validation error: #{err.message} (code: #{err.code})")
    end

    KubeMQ.Client.close(client)

  {:error, reason} ->
    IO.puts("Could not connect: #{inspect(reason)}")
end

How It Works

• start_link/1 returns {:error, reason} when the server is unreachable
• Guard clauses when is_exception(err) distinguish structured errors from raw terms
• Sending to an empty channel triggers a validation error with code :validation

Related

• Reconnection
• Graceful Shutdown
• Types & Errors Reference