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();
}

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