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_pac_exception(). Callers should chain causes explicitly: raise _convert_pac_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

Server ResultCode when the failure came from a result code; None for purely client-side issues (for example connection setup).

in_doubt

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

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)

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.

result_code

Set when the server returned a timeout-related code; otherwise often None for client-side timeouts.

See also

ConnectionError: Cluster reachability rather than deadline

exceeded.

Example::

try:

await stream.first_or_raise()

except TimeoutError:

… # retry or fall back

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

Usually None because the failure occurs before a server result code is available.

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

Usually None.

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.QueryTerminatedError

Bases: AerospikeError

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.

result_code

May include ResultCode.QUERY_ABORTED or related codes.

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.CommitError

Bases: AerospikeError

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.

verify_records

Verify-phase records or summaries, if available.

roll_records

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

result_code

Server or client result associated with the commit, when set.

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)

AEL exceptions

Exceptions raised by the Aerospike Expression Language (AEL).

exception aerospike_sdk.ael.exceptions.AelParseException

Bases: Exception

Raised when a filter expression string cannot be parsed or validated.

Indicates invalid syntax, unknown operators, type mismatches, or other input that the AEL layer refuses before building a server-side filter.

Example

Handling a user-supplied filter string:

from aerospike_sdk import parse_ael, AelParseException

try:
    expr = parse_ael(user_filter)
except AelParseException as e:
    raise ValueError(str(e)) from e

See also

parse_ael(): Primary entry point that may raise

this exception.

exception aerospike_sdk.ael.exceptions.NoApplicableFilterError

Bases: Exception

Internal signal that no secondary-index filter can represent an expression.

Used inside the AEL filter visitor when a valid parse tree still cannot be lowered to a secondary-index filter. Not part of the public stable API; callers working only with parse_ael() should expect AelParseException instead.