Exceptions

Typed exceptions for the SDK client.

Subclasses of AerospikeError mirror common server and client outcomes so callers can handle failures selectively (for example except GenerationError) instead of comparing result codes everywhere.

At public boundaries, errors from the underlying async client are normalized with _convert_pnc_exception(). Callers should chain causes explicitly: raise _convert_pnc_exception(exc) from exc.

exception aerospike_sdk.exceptions.AerospikeError

Bases: Exception

Base class for SDK failures.

Raised directly when no more specific subclass applies, including unmapped server result codes (see _result_code_to_exception()). Prefer catching concrete subclasses when you need targeted handling, and fall back to this type for all other Aerospike-related errors.

result_code

The ResultCode of the failure. A server failure carries the code the server returned; a failure the client raised on its own carries a client code (ResultCode.SERVER_NOT_AVAILABLE, ResultCode.TXN_FAILED), the same negative number every Aerospike client reports for it. None only on an instance built by hand.

in_doubt

True when a write may have completed on the server despite the error; safe retry usually requires a read-verify strategy.

sub_code

Server-supplied numeric subcode refining result_code when extended error detail was requested (see error_detail_verbosity). None means no detail was returned (verbosity off, or a client-side failure); 0 (SubCode.NONE) means detail was returned but this failure has no finer subcode than its result code. Only meaningful together with result_code — subcode values are scoped to their parent code, not globally unique.

server_message

Human-readable message from the server when detail was requested at message-level verbosity or higher; None when no detail was returned. May be present even when sub_code is 0.

hint

Client-side guidance for result codes whose cause is a common, recognizable misconfiguration – appended to the message and kept here separately so callers can log or suppress it independently. None when the SDK has nothing to add beyond what the server reported. Unlike server_message this is generated locally and never travels the wire.

exp_trace

Structured expression trace the server attaches to expression-build failures at trace-level verbosity; None otherwise. Surfaced as an opaque passthrough of the underlying client value.

node

Cluster node the failing attempt targeted, when the retry loop recorded one; None for failures that never reached node selection (for example, argument validation).

iteration

Number of attempts made before the command failed, when recorded; None when the failure precedes the retry loop.

sub_exceptions

Exceptions from prior retry attempts of the same command, oldest first, each converted to this hierarchy. Empty when the command was not retried.

base_message

The failure message without the retry-context decoration the full message carries; None when no undecorated form was recorded.

Example::

try:

stream = await session.query(key).bins([“x”]).execute() await stream.first_or_raise()

except AerospikeError as err:

code = err.result_code …

See also

_result_code_to_exception(): Maps result codes to this type or a

subclass.

__init__(message='', *, result_code=None, in_doubt=False, sub_code=None, server_message=None, exp_trace=None, node=None, iteration=None, sub_exceptions=(), base_message=None, hint=None)

exception aerospike_sdk.exceptions.TimeoutError

Bases: AerospikeError

Raised when an operation exceeds a client or server timeout.

Covers socket-level timeouts and server-reported timeout result codes. This type shares a name with Python’s built-in TimeoutError; always import it from aerospike_sdk or this module when handling SDK client timeouts.

client

True when the client’s own deadline fired (socket or total timeout expired locally); False when the server reported the timeout result code. A client timeout says nothing about server-side progress — pair it with in_doubt when deciding whether a write needs read-verification.

result_code

ResultCode.TIMEOUT when the server reported it or the total timeout expired, so both classify alike; ResultCode.MAX_RETRIES_EXCEEDED when every attempt the policy allowed failed before that deadline – including the only attempt when retries are off, so a single socket timeout with max_retries=0 reports this code too.

See also

ConnectionError: Cluster reachability rather than deadline

exceeded.

Example::

try:

await stream.first_or_raise()

except TimeoutError as err:

if err.client:

… # local deadline; the server may still be working

else:

… # the server itself timed the operation out

__init__(message='', *, client=False, **kwargs)

exception aerospike_sdk.exceptions.ConnectionError

Bases: AerospikeError

Raised when the client cannot establish or keep a cluster connection.

Typical causes include refused sockets, TLS handshake failure, or loss of connectivity mid-flight. Distinct from TimeoutError, which signals a deadline rather than an immediate transport failure.

result_code

ResultCode.SERVER_NOT_AVAILABLE when no node could be reached, or the code of the failure that cut the connection.

Example::

try:

async with Client(…) as client:

…

except ConnectionError:

… # cluster unreachable

exception aerospike_sdk.exceptions.InvalidNodeError

Bases: AerospikeError

Raised when the chosen node is unknown, wrong role, or not usable.

Use for diagnosing cluster topology or client routing issues rather than application-level data errors.

result_code

ResultCode.INVALID_NODE_ERROR (-3).

exception aerospike_sdk.exceptions.InvalidNamespaceError

Bases: AerospikeError

Raised when the namespace is missing or not defined on the cluster.

Often indicates a configuration mismatch between application and cluster.

result_code

Typically ResultCode.INVALID_NAMESPACE when mapped from a server response.

Example::

try:

await session.query(bad_ds).execute()

except InvalidNamespaceError:

… # namespace not configured on cluster

exception aerospike_sdk.exceptions.SecurityError

Bases: AerospikeError

Base class for authentication, authorization, and security policy errors.

Several distinct server result codes collapse to this type when they do not warrant a dedicated subclass. Catch AuthenticationError or AuthorizationError first if you need finer granularity.

result_code

The security-related code returned by the server, when applicable.

exception aerospike_sdk.exceptions.AuthenticationError

Bases: SecurityError

Raised when credentials are rejected or the session is not authenticated.

Examples include invalid user, expired password, or not authenticated responses from the server.

See also

AuthorizationError: Valid identity but disallowed operation.

exception aerospike_sdk.exceptions.AuthorizationError

Bases: SecurityError

Raised when the authenticated principal may not perform the operation.

Distinct from AuthenticationError, which indicates identity or credential problems rather than policy denial.

exception aerospike_sdk.exceptions.GenerationError

Bases: AerospikeError

Raised when a write fails due to a record generation mismatch.

The record was modified since it was read, or the expected generation did not match. Retrying blindly usually requires re-reading the record and reapplying the logical update.

result_code

Typically ResultCode.GENERATION_ERROR.

Example:

try:
    await (
        session.upsert(key)
            .put({"x": 1})
            .ensure_generation_is(3)
            .execute()
    )
except GenerationError:
    ...  # record was modified by another writer

See also

upsert(): Common write path

that can enforce generations on builders.

exception aerospike_sdk.exceptions.QuotaError

Bases: AerospikeError

Raised when a server-side quota or limit is exceeded.

Handling is usually operational (throttle, increase limits, or partition workload) rather than a single-record retry.

exception aerospike_sdk.exceptions.SerializationError

Bases: AerospikeError

Raised when a value cannot be encoded for the wire or decoded from it.

Check bin types and application serializers when this appears on puts or reads.

exception aerospike_sdk.exceptions.RecordNotFoundError

Bases: AerospikeError

Raised when no record exists for the requested key.

Surfaces on reads and on writes that require an existing record (update, replace, touch), and on batch/point reads when include_missing_keys() promotes a not-found key to an error result.

result_code

ResultCode.KEY_NOT_FOUND_ERROR.

Example:

try:
    await session.update(key).put({"count": 1}).execute_or_raise()
except RecordNotFoundError:
    ...  # nothing to update

exception aerospike_sdk.exceptions.RecordExistsError

Bases: AerospikeError

Raised when a create-only write finds the key already present.

Produced by insert-style (create-only) writes when a record already exists for the key; the idiomatic way to detect a duplicate on insert.

result_code

ResultCode.KEY_EXISTS_ERROR.

Example:

try:
    await session.insert(key).put({"count": 1}).execute_or_raise()
except RecordExistsError:
    ...  # key already taken

exception aerospike_sdk.exceptions.RecordTooBigError

Bases: AerospikeError

Raised when a record exceeds the server’s configured size limit.

Reduce the bin payload or raise the namespace’s size ceiling; retrying the same record unchanged will fail again.

result_code

ResultCode.RECORD_TOO_BIG.

exception aerospike_sdk.exceptions.FilteredOutError

Bases: AerospikeError

Raised when an operation is skipped because its filter expression was false.

Only surfaces as an error when fail_on_filtered_out() is set; otherwise a filtered record is silently omitted from results.

result_code

ResultCode.FILTERED_OUT.

See also

RecordNotFoundError: A missing record rather than a filter miss.

exception aerospike_sdk.exceptions.BinError

Bases: AerospikeError

Base class for bin-level failures.

Covers an over-long bin name and serves as the parent for the more specific bin errors below; catch this to handle any bin-scoped failure at once.

result_code

A bin-related code such as ResultCode.BIN_NAME_TOO_LONG.

exception aerospike_sdk.exceptions.BinExistsError

Bases: BinError

Raised when a create-only bin operation finds the bin already present.

result_code

ResultCode.BIN_EXISTS_ERROR.

exception aerospike_sdk.exceptions.BinNotFoundError

Bases: BinError

Raised when an update-only bin operation targets a missing bin.

result_code

ResultCode.BIN_NOT_FOUND.

exception aerospike_sdk.exceptions.BinTypeError

Bases: BinError

Raised when an operation is incompatible with the bin’s stored type.

For example, arithmetic on a bin holding a string. Distinct from BinOpInvalidError, which concerns the bin’s current value.

result_code

ResultCode.BIN_TYPE_ERROR.

exception aerospike_sdk.exceptions.BinOpInvalidError

Bases: BinError

Raised when an operation cannot be applied to the bin’s current value.

For example, a list operation against a bin that does not hold a list.

result_code

ResultCode.OP_NOT_APPLICABLE.

exception aerospike_sdk.exceptions.ElementError

Bases: AerospikeError

Base class for list/map element-level failures inside CDT operations.

exception aerospike_sdk.exceptions.ElementNotFoundError

Bases: ElementError

Raised when a list index or map key is absent under an update-only mode.

result_code

ResultCode.ELEMENT_NOT_FOUND.

exception aerospike_sdk.exceptions.ElementExistsError

Bases: ElementError

Raised when a list index or map key is present under a create-only mode.

result_code

ResultCode.ELEMENT_EXISTS.

exception aerospike_sdk.exceptions.CapacityError

Bases: AerospikeError

Raised on server or client resource exhaustion.

Covers server memory pressure, device I/O overload, and full server-side queues. Handling is operational (throttle, retry with backoff, or add capacity) rather than a single-record retry.

result_code

A capacity-related code such as ResultCode.SERVER_MEM_ERROR or ResultCode.DEVICE_OVERLOAD.

exception aerospike_sdk.exceptions.KeyBusyError

Bases: CapacityError

Raised when too many concurrent operations target one record (hot key).

A transient contention signal; a brief backoff before retry usually clears it. Catch CapacityError to handle it alongside other exhaustion.

result_code

ResultCode.KEY_BUSY.

exception aerospike_sdk.exceptions.SecondaryIndexError

Bases: AerospikeError

Base class for secondary-index management failures.

Named SecondaryIndexError rather than IndexError so it does not shadow the built-in IndexError. Covers index creation limits, out-of-memory, and not-readable states; catch this for any index failure.

result_code

An index-related code such as ResultCode.INDEX_OOM.

exception aerospike_sdk.exceptions.IndexNotFoundError

Bases: SecondaryIndexError

Raised when a referenced secondary index does not exist.

result_code

ResultCode.INDEX_NOT_FOUND.

exception aerospike_sdk.exceptions.IndexAlreadyExistsError

Bases: SecondaryIndexError

Raised when creating a secondary index that already exists.

result_code

ResultCode.INDEX_FOUND.

exception aerospike_sdk.exceptions.QueryError

Bases: AerospikeError

Base class for query and scan execution failures.

Covers generic query errors, aborted scans, and query network failures. Timeout-flavored query codes raise TimeoutError instead, and a full query queue raises CapacityError — catch this class for failures of the query itself.

result_code

A query-related code such as ResultCode.QUERY_GENERIC or ResultCode.SCAN_ABORT.

exception aerospike_sdk.exceptions.QueryTerminatedError

Bases: QueryError

Raised when a query stops early (aborted, canceled, or server-terminated).

Partial rows may already have been delivered on streaming paths; this error represents the overall query outcome, not a single-key failure inside a batch. Catch QueryError to handle it alongside other query failures.

result_code

ResultCode.QUERY_ABORTED or a related server code, or ResultCode.SCAN_TERMINATED when the client cut the stream short.

exception aerospike_sdk.exceptions.UdfError

Bases: AerospikeError

Raised when a server-side UDF execution reports a failure.

The server ran the registered function and it returned an error (or the response was not a valid UDF result). The failure detail is in the message; check the UDF’s own error string when debugging Lua code.

result_code

ResultCode.UDF_BAD_RESPONSE.

Example:

try:
    await session.execute_udf(key).function("mod", "fn").execute()
except UdfError:
    ...  # the function itself failed on the server

exception aerospike_sdk.exceptions.BatchError

Bases: AerospikeError

Raised when the server’s batch subsystem rejects a batch request.

Signals a batch-level condition (for example, batch disabled on the server) rather than a per-key failure — per-key outcomes surface as RecordResult errors in the stream. Full batch queues raise CapacityError instead.

result_code

A batch-related code such as ResultCode.BATCH_DISABLED.

exception aerospike_sdk.exceptions.BackoffError

Bases: AerospikeError

Raised when the server signals rate limiting or requires backoff.

Callers may retry after a delay or reduce request pressure.

exception aerospike_sdk.exceptions.MaxErrorRateError

Bases: BackoffError

Raised when the client’s per-node circuit breaker trips.

The breaker is governed by Client(...)’s max_error_rate and error_rate_window keywords (or ClientPolicy fields of the same name). Once a node’s error count crosses max_error_rate within the current window, subsequent commands routed to that node fail fast with this exception until the next window resets. Catch BackoffError to handle this together with other server-side backoff signals.

Example:

try:
    await session.read(key).execute()
except MaxErrorRateError:
    ...  # node is in cooldown; route around it or wait

exception aerospike_sdk.exceptions.TransactionError

Bases: AerospikeError

Base class for multi-record transaction (MRT) failures.

Covers a transaction that is blocked, expired, aborted, already committed, version-mismatched, or has exceeded its write limit. CommitError is the commit-phase specialization; catch this base to handle any MRT failure at once.

result_code

An MRT-related server code such as ResultCode.MRT_EXPIRED, or ResultCode.TXN_FAILED when the client refuses to continue a transaction whose commit already failed.

exception aerospike_sdk.exceptions.CommitError

Bases: TransactionError

Raised when a multi-record transaction commit does not complete successfully.

Additional fields expose verify or roll-forward details when the underlying client provides them.

commit_error_type

Implementation-defined label for the failure phase, if available. ROLL_FORWARD_ABANDONED means the writes are not yet visible; the server will eventually commit them, so a retry of the same work is not safe.

verify_records

Verify-phase records or summaries, if available.

roll_records

Roll-forward or rollback-phase records, if available.

result_code

The server code that tripped the failing stage when there was one, otherwise ResultCode.TXN_FAILED.

in_doubt

Inherited; True when commit outcome may be ambiguous on the server.

__init__(message='', *, commit_error_type=None, verify_records=None, roll_records=None, result_code=None, in_doubt=False, **kwargs)