Error handling

The three execution modes

Every builder’s .execute() method supports three modes that control how per-record errors are surfaced:

Mode	Java	Python	Behavior	Best for
Default	execute()	await … .execute()	Single-key: throws immediately. Batch: errors embedded in stream	Simple cases
In-stream errors	execute(ErrorStrategy.IN_STREAM)	await … .execute(on_error=ErrorStrategy.IN_STREAM)	All errors embedded as RecordResult entries in the stream	Uniform handling of single + batch
Error callback	execute(errorHandler)	await … .execute(on_error=<callable>)	Errors dispatched to callback, excluded from stream	Logging, fire-and-forget

Java exposes the same three modes through overloads of execute() and executeAsync(). The Python SDK uses await … .execute(on_error=…) as the entry point for the async surface (aerospike_sdk.aio.*); the synchronous surface (aerospike_sdk.sync.*) offers the same builders with blocking .execute(on_error=…) calls. Either way there is no separate executeAsync() — choosing async vs sync is a matter of which session/client class you import.

Mode 1: Default (execute())

Single-key operations throw on failure:

Java

try {
    session.update(users.id("no-such-key"))
        .bin("name").setTo("Alice")
        .execute();
} catch (AerospikeException e) {
    System.out.println("Failed: " + e.getResultCode()); // 2 = KEY_NOT_FOUND_ERROR
}

📖 API reference: DataSet.id(...) | Session.update(DataSet) | ChainableOperationBuilder.bin(...) | ChainableQueryBuilder.bin(...) | ChainableQueryBuilder.execute() | AerospikeException

Python

from aerospike_sdk import AerospikeError

try:
    await (
        session.update(users.id("no-such-key"))
        .bin("name").set_to("Alice")
        .execute()
    )
except AerospikeError as e:
    print(f"Failed: {e.result_code}")  # 2 = KEY_NOT_FOUND_ERROR

📖 API reference: DataSet.id() | Session.update() | QueryBuilder.bin() | WriteSegmentBuilder.set_to() | WriteSegmentBuilder.bin() | WriteSegmentBuilder.execute()

Batch operations embed errors in the stream:

Java

RecordStream stream = session
    .update(users.id("exists"))
        .bin("count").add(1)
    .update(users.id("no-such-key"))
        .bin("count").add(1)
    .execute();

stream.forEach(result -> {
    if (result.isOk()) {
        System.out.println(result.getKey().userKey + ": success");
    } else {
        System.out.println(result.getKey().userKey + ": " + result.getMessage());
    }
});

📖 API reference: DataSet.id(...) | ChainableQueryBuilder.bin(...) | BinBuilder.add(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordResult.isOk()

Python

stream = await (
    session.update(users.id("exists"))
        .bin("count").add(1)
    .update(users.id("no-such-key"))
        .bin("count").add(1)
    .execute()
)
try:
    async for result in stream:
        if result.is_ok:
            print(f"{result.key.value}: success")
        else:
            print(f"{result.key.value}: {result.to_exception()}")
finally:
    stream.close()

📖 API reference: DataSet.id() | Session.update() | QueryBuilder.bin() | WriteSegmentBuilder.bin() | RecordStream.close() | WriteSegmentBuilder.execute()

Mode 2: ErrorStrategy.IN_STREAM

Forces all errors (including single-key) into the stream. Useful when you want uniform handling regardless of key count:

Java

RecordStream stream = session.update(users.id("no-such-key"))
    .bin("name").setTo("Alice")
    .execute(ErrorStrategy.IN_STREAM);

stream.forEach(result -> {
    if (!result.isOk()) {
        System.out.println("Error: " + result.getResultCode() + " - " + result.getMessage());
    }
});

📖 API reference: DataSet.id(...) | Session.update(DataSet) | ChainableOperationBuilder.bin(...) | ChainableQueryBuilder.bin(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordResult.isOk() | ErrorStrategy | ErrorStrategy.IN_STREAM

Python

from aerospike_sdk import ErrorStrategy

stream = await (
    session.update(users.id("no-such-key"))
    .bin("name").set_to("Alice")
    .execute(on_error=ErrorStrategy.IN_STREAM)
)
try:
    async for result in stream:
        if not result.is_ok:
            print(f"Error: {result.result_code} - {result.to_exception()}")
finally:
    stream.close()

📖 API reference: DataSet.id() | Session.update() | QueryBuilder.bin() | WriteSegmentBuilder.set_to() | WriteSegmentBuilder.bin() | RecordStream.close() | WriteSegmentBuilder.execute()

Mode 3: ErrorHandler callback

Errors are dispatched to the handler and excluded from the stream. The stream contains only successful results:

Java

RecordStream stream = session
    .upsert(users.id("u1")).bin("name").setTo("Alice")
    .upsert(users.id("u2")).bin("name").setTo("Bob")
    .execute((key, index, exception) ->
        System.err.println("Failed key " + key.userKey +
            " at index " + index + ": " + exception.getMessage())
    );

// stream contains only successful results
stream.forEach(result -> {
    System.out.println(result.getKey().userKey + ": OK");
});

📖 API reference: DataSet.id(...) | ChainableQueryBuilder.bin(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...)

Python

def handle_error(key, index, ex):
    print(f"Failed key {key.value} at index {index}: {ex}")

stream = await (
    session.upsert(users.id("u1")).bin("name").set_to("Alice")
    .upsert(users.id("u2")).bin("name").set_to("Bob")
    .execute(on_error=handle_error)
)
# stream contains only successful results
try:
    async for result in stream:
        print(f"{result.key.value}: OK")
finally:
    stream.close()

📖 API reference: DataSet.id() | Session.upsert() | QueryBuilder.bin() | WriteSegmentBuilder.set_to() | WriteSegmentBuilder.bin() | RecordStream.close() | WriteSegmentBuilder.execute()

Inspecting RecordResult

Every result in the stream is a RecordResult. Key members:

Java	Python	Returns	Throws?
isOk()	is_ok (attribute)	true if result_code == OK	No
getResultCode()	result_code (attribute)	Integer result code	No
getMessage()	server_message (attribute; set when the Behavior’s error_detail_verbosity is MESSAGE)	Human-readable error message (or null/None)	No
toException()	to_exception()	The failure as an exception without throwing it. Check isOk() first in Java: on an OK row Java returns an exception carrying code 0, while Python returns None	No
orThrow()	or_raise()	self if OK, throws otherwise	Yes
recordOrThrow()	record_or_raise()	The Record if OK, throws otherwise	Yes
getRecord()	record (attribute, may be None)	The Record or null/None — does not throw	No
asBoolean()	as_bool()	true if OK, false if KEY_NOT_FOUND, throws otherwise	Conditionally
getKey()	key (attribute; user value in key.value)	The Key for this operation	No
getIndex()	index (attribute)	Position in the batch (0-based)	No
isInDoubt()	in_doubt (attribute)	Whether the write may have succeeded on the server	No
getException()	exception (attribute)	The AerospikeException / AerospikeError the client attached, or null/None (server-reported row failures carry only a result code; use toException() / to_exception())	No

Using failures() to isolate errors

RecordStream.failures() consumes the entire source stream and returns only the failed results. In Java this is a new RecordStream; in Python it is an awaitable that resolves to list[RecordResult].

Java

RecordStream stream = session
    .update(users.id("u1")).bin("count").add(1)
    .update(users.id("u2")).bin("count").add(1)
    .update(users.id("missing")).bin("count").add(1)
    .execute(ErrorStrategy.IN_STREAM);

RecordStream errors = stream.failures();
errors.forEach(failure ->
    System.err.println("Failed: " + failure.getKey().userKey + " → " + failure.getMessage())
);

📖 API reference: DataSet.id(...) | ChainableQueryBuilder.bin(...) | BinBuilder.add(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | ErrorStrategy | ErrorStrategy.IN_STREAM

Python

from aerospike_sdk import ErrorStrategy

stream = await (
    session.update(users.id("u1")).bin("count").add(1)
    .update(users.id("u2")).bin("count").add(1)
    .update(users.id("missing")).bin("count").add(1)
    .execute(on_error=ErrorStrategy.IN_STREAM)
)
errors = await stream.failures()
for f in errors:
    print(f"Failed: {f.key.value} → {f.to_exception()}")
stream.close()

📖 API reference: DataSet.id() | Session.update() | QueryBuilder.bin() | WriteSegmentBuilder.bin() | RecordStream.failures() | RecordStream.close() | WriteSegmentBuilder.execute()

Note

failures() is a terminal-style helper — it drains and exhausts the source stream and returns the failures fully in memory (a new RecordStream in Java; a list[RecordResult] in Python). In Python it does not call stream.close() for you; if you need to release client/server resources promptly, call stream.close() (or wrap the work in try / finally) after collecting the failures.

Existence checks

The asBoolean() / as_bool() method translates as follows:

• OK → true
• KEY_NOT_FOUND → false
• any other error → throws:

Java

boolean exists = session.exists(users.id("user-1"))
    .execute()
    .getFirstBoolean()
    .orElse(false);

📖 API reference: DataSet.id(...) | Session.exists(Key) | ChainableQueryBuilder.execute()

Python

exists = (await session.exists(users.id("user-1")).first()).as_bool()

📖 API reference: DataSet.id() | Session.exists() | RecordResult.as_bool() | RecordStream.first() | RecordStream.close() | WriteSegmentBuilder.execute()

Decision guide

Scenario	Recommended mode
Simple single-key read/write	execute() + try/catch
Batch where all failures are fatal	execute() + iterate and check isOk() / is_ok
Batch where you need consistent handling	execute(ErrorStrategy.IN_STREAM) (Java) / execute(on_error=ErrorStrategy.IN_STREAM) (Python)
Batch where failures should be logged but not block	execute(errorHandler) (Java) / execute(on_error=<callable>) (Python)
Need to collect all failures for retry	IN_STREAM mode + .failures()

Malformed AEL text

AEL strings must conform to the AEL reference grammar, but neither SDK parses or validates AEL text locally. .where(...), selectFrom(...) / select_from(...), and the write-side *From(...) builders send the AEL string to the server as-is; the server parses and compiles it as part of each request. There is no local syntax check before sending, and no dedicated exception type for an AEL syntax error — a malformed expression comes back as an ordinary AerospikeException (Java) / AerospikeError (Python) from that request, typically carrying ResultCode.PARAMETER_ERROR.

Java

try {
    // Single-quoted strings and '==' are required; '=' is a parse error
    session.query(users).where("$.name = 'Alice'").execute();
} catch (AerospikeException e) {
    if (e.getResultCode() == ResultCode.PARAMETER_ERROR) {
        // Malformed AEL syntax, or another rejected argument
    }
}

📖 API reference: AerospikeException | AerospikeException.getResultCode() | ResultCode | Cluster.supportsAel()

Python

from aerospike_sdk import AerospikeError, ResultCode

try:
    # Single-quoted strings and '==' are required; '=' is a parse error
    stream = await session.query(users).where("$.name = 'Alice'").execute()
except AerospikeError as e:
    if e.result_code == ResultCode.PARAMETER_ERROR:
        pass  # Malformed AEL syntax, or another rejected argument

📖 API reference: AerospikeError | ResultCode | Cluster.supports_ael()

PARAMETER_ERROR covers any rejected argument, not only AEL syntax, and the server does not always send a specific reason unless asked. Set errorDetailVerbosity / error_detail_verbosity to MESSAGE on the session’s Behavior to have the server’s explanation returned with the error. For parse coordinates, build traces, and filter-decision explainers specific to AEL text, see Debug AEL expressions. To catch AEL mistakes before they reach production, test the expression against Aerospike Voyager or a live server — there is no local syntax check to catch them earlier.

On a cluster that doesn’t support server-side AEL compilation, a string .where() call raises the same exception type instead, carrying ResultCode.OP_NOT_APPLICABLE — check Cluster.supportsAel() (Java) / cluster.supports_ael() (Python) up front, or fall back to the programmatic expression builder, to avoid depending on string AEL there.

Next steps

Handle errors gracefully

Learn the Java/Python exception hierarchy and retry strategies.

Handle errors gracefully →

Query records

Build queries and AEL filters that pair with these execution modes.

Query records →

Common issues

Troubleshoot frequent error scenarios.

Common issues →