Error handling
For the complete documentation index see: llms.txt
All documentation pages available in markdown.
The java client can throw the following runtime exceptions:
| Exception | Description |
|---|---|
| AerospikeException | Base exception. A more specific error code can be obtained by getResultCode(). View Result Codes |
| AerospikeException.Timeout | Command has timed out. |
| AerospikeException.Serialize | Error using java or messagepack encoding/decoding. |
| AerospikeException.Parse | Error parsing server response. |
| AerospikeException.Connection | Error establishing connection to server node. |
| AerospikeException.InvalidNode | The chosen node is not active or a namespace is removed while the client is active. |
| AerospikeException.ScanTerminated | Scan was terminated prematurely. |
| AerospikeException.QueryTerminated | Query was terminated prematurely. |
| AerospikeException.AsyncQueueFull | Async command was rejected because the async delay queue is full. |
Here is example code that handles an AerospikeException.
AerospikeClient client = new AerospikeClient("192.168.1.150", 3000);
try { try { client.put(null, new Key("test", "demo", "key"), new Bin("testbin", 32)); } catch (AerospikeException.Timeout aet) { // Handle timeouts differently. retryTransaction(); } catch (AerospikeException ae) { throw new MyException("AerospikeException " + ae.getResultCode() + ": " + ae.getMessage()); }}finally { client.close();}Result codes
getResultCode() returns one of the constants in com.aerospike.client.ResultCode.
Compare against the constant rather than its number.
The following result codes come from common single-record commands.
| Constant | Value | Cause |
|---|---|---|
ResultCode.KEY_NOT_FOUND_ERROR | 2 | The command requires an existing record, but none was found. Examples include RecordExistsAction.UPDATE_ONLY writes and touch commands. client.get() returns null instead of throwing. |
ResultCode.GENERATION_ERROR | 3 | A write with GenerationPolicy.EXPECT_GEN_EQUAL found a different generation. |
ResultCode.KEY_EXISTS_ERROR | 5 | A write with RecordExistsAction.CREATE_ONLY found an existing record. |
ResultCode.BIN_TYPE_ERROR | 12 | An operation doesn’t apply to the bin’s type, such as add on a string bin. |
ResultCode.ELEMENT_EXISTS | 24 | A list or map write with a unique or create-only flag found the element already present, and the NO_FAIL flag isn’t set. |
ResultCode.INDEX_NOTFOUND | 201 | A query filters on a bin that has no secondary index. |
ResultCode.getResultString(code) returns a short description of a result code, which is useful for logging.
catch (AerospikeException ae) { if (ae.getResultCode() == ResultCode.KEY_EXISTS_ERROR) { // The record already exists } else { System.out.println(ResultCode.getResultString(ae.getResultCode())); }}Batch commands don’t throw for a failed record. Each BatchRecord holds its own resultCode. See Create-only writes.
Server error details
Aerospike Database 8.2.0 and later can return structured error details on failed operations: a stable numeric subcode, a message written at the failure site, and, at the highest verbosity, an expression trace. The Aerospike Java client 10.5.0 and later can read those details. Opt in by setting errorDetailVerbosity on the operation policy, then read the details from the exception:
import com.aerospike.client.AerospikeClient;import com.aerospike.client.AerospikeException;import com.aerospike.client.Key;import com.aerospike.client.Record;import com.aerospike.client.policy.Policy;
AerospikeClient client = new AerospikeClient("192.168.1.150", 3000);Key key = new Key("test", "demo", "key");Policy policy = new Policy(client.readPolicyDefault);policy.errorDetailVerbosity = 2;
try { Record record = client.get(policy, key);}catch (AerospikeException ae) { System.out.println("status=" + ae.getResultCode() + " subcode=" + ae.getSubCode() + " message=" + ae.getMessage());}finally { client.close();}getSubCode() returns the subcode (note the capital C), or 0 when the server omitted one. Dispatch on the (status, subcode) pair only when the subcode is nonzero. Constants are in the SubCode class. See Error subcodes. getMessage() always begins with Error <resultCode>,<subCode>[,iteration][,timeouts][,inDoubt][,node]: , where each bracketed part appears only when set, followed by the server’s detail text at verbosity 2 and up, or the client’s generic result-code text otherwise. getExpressionTrace() returns a structured ExpressionTrace at verbosity 3 when the failure involved an expression, or null otherwise; see Expression traces for the trace shape. BatchRecord carries the same detail per row.
See Server error details for verbosity levels, coverage, and operator caps, and the Client matrix for the Java client version that pairs with Database 8.2.0.