Aerospike.Error exception (Aerospike Driver v0.3.1)

Exception raised for Aerospike client and server errors.

Result codes from the wire protocol are represented as atoms (e.g. :key_not_found, :timeout). Use from_result_code/2 to build an error from a result code atom.

Summary

Types

exception_input()

Input accepted by exception/1.

option()

Option accepted when constructing an Aerospike.Error.

opts()

Keyword options accepted when constructing an Aerospike.Error.

t()

Aerospike client or server error.

Functions

exception(msg)

Builds an exception struct from keyword, map, string, or atom input.

from_result_code(code, opts \\ [])

Builds an error struct from a result code atom.

message(exception)

Formats the error for exception messages.

rebalance?(arg1)

Returns true when the error represents a cluster rebalance / partition- ownership signal that should trigger a re-route rather than a same-replica retry.

Types

exception_input()

@type exception_input() :: opts() | map() | String.t() | atom()

Input accepted by exception/1.

option()

@type option() ::
  {:code, atom()}
  | {:message, String.t()}
  | {:node, String.t() | nil}
  | {:in_doubt, boolean()}

Option accepted when constructing an Aerospike.Error.

opts()

@type opts() :: [option()]

Keyword options accepted when constructing an Aerospike.Error.

t()

@type t() :: %Aerospike.Error{
  __exception__: true,
  code: atom(),
  in_doubt: boolean(),
  message: String.t(),
  node: String.t() | nil
}

Aerospike client or server error.

:code is the normalized result-code atom used by the public API. :node is set when the failing operation can attribute the error to one cluster node. :in_doubt is true when a write-style operation may have reached the server before the client observed the failure.

Functions

exception(msg)

@spec exception(exception_input()) :: t()

Builds an exception struct from keyword, map, string, or atom input.

Keyword and map input may include :code, :message, :node, and :in_doubt. String input becomes a client error message, and atom input is treated as an Aerospike result code.

from_result_code(code, opts \\ [])

@spec from_result_code(atom(), opts()) :: t()

Builds an error struct from a result code atom.

The default human-readable message is derived from the result code. Options:

:message — override the message string
:node — optional node name (for cluster-aware errors)
:in_doubt — whether the outcome is uncertain (default false)

Examples

iex> e = Aerospike.Error.from_result_code(:key_not_found)
iex> e.code
:key_not_found
iex> e.in_doubt
false

iex> e = Aerospike.Error.from_result_code(:timeout, node: "BB9", in_doubt: true)
iex> e.node
"BB9"
iex> e.in_doubt
true

message(exception)

@spec message(t()) :: String.t()

Formats the error for exception messages.

rebalance?(arg1)

@spec rebalance?(t() | term()) :: boolean()

Returns true when the error represents a cluster rebalance / partition- ownership signal that should trigger a re-route rather than a same-replica retry.

Rebalance-class errors mean "the server you addressed does not own this partition right now" — the retry layer consumes this as a cue to pick the next replica (and usually to ask the Tender for a fresh partition map). Transport errors (:network_error, :timeout, pool errors) and server errors unrelated to ownership (:key_not_found, :generation_error, etc.) are not rebalance-class.

Accepts t/0 or any value; non-Error values (including bare atoms like :cluster_not_ready) return false so callers can pattern-match uniformly on whatever the command path returned.

Examples

iex> err = Aerospike.Error.from_result_code(:partition_unavailable)
iex> Aerospike.Error.rebalance?(err)
true

iex> err = Aerospike.Error.from_result_code(:key_not_found)
iex> Aerospike.Error.rebalance?(err)
false

iex> Aerospike.Error.rebalance?(:cluster_not_ready)
false