Error handling

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Each database operation accepts an as_error object as an argument. When an error occurs during an operation, the as_error argument is populated with the status code and error information. The as_error argument is usually the second argument to a database operation.

The as_error object provides the following information:

code, the as_status of the operation.
subcode, the server error-detail subcode when the request policy sets error_detail_verbosity ≥ 1 and the server returns structured details. Zero (AS_SUB_NONE) when the server omitted a subcode. Dispatch on the (code, subcode) pair only when subcode is nonzero. See Error subcodes.
message, the message that corresponds to an error code. When the server returns a detail message, the client folds it into this field (for example, "can't create record: namespace or set is truncated (subcode=6)"). At verbosity level 2, messages can expose set or bin names. See Server error details and error-details-max-verbosity. If the operation completed successfully, this can be an empty string.
func, the function in which the error occurred. If it was not captured properly in the operation, this can be NULL.
file, the file in which the error occurred. If it was not captured properly in the operation, this can be NULL.
line, the line number in the file where the error occurred. If it was not captured properly in the operation, this can be 0.

When an operation completes, it returns an as_status that corresponds to the as_error.code. If an operation returns a failure status, anything not AEROSPIKE_OK, then the application must check the as_error variable for more information. See as_status.h for a complete list.

An as_error can be reused between operations, because each operation resets the as_error and sets on error.

The following example handles the error from an operation. It assumes an established connection (as) and initialized key and rec, as shown in Connecting.

#include <stdio.h>
#include <aerospike/aerospike.h>

as_error err;
if (aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
    fprintf(stderr, "err(%d) %s at [%s:%d]\n", err.code, err.message, err.file, err.line);
}

The application can do more elaborate error handling.

Server error details

Aerospike Database 8.2.0 and later can return a numeric subcode and human-readable message on failed operations. Opt in by setting error_detail_verbosity on as_policy_base before the operation. This fragment uses the same as, key, and rec as the preceding example.

#include <stdio.h>
#include <aerospike/aerospike.h>
#include <aerospike/as_policy.h>
#include <aerospike/as_subcode.h>

as_policy_write policy;
as_policy_write_init(&policy);
policy.base.error_detail_verbosity = AS_ERROR_DETAIL_MESSAGE;

as_error err;
if (aerospike_key_put(&as, &err, &policy, &key, &rec) != AEROSPIKE_OK) {
    fprintf(stderr, "status=%d subcode=%u %s\n", err.code, err.subcode, err.message);
}

Verbosity levels are AS_ERROR_DETAIL_NONE, AS_ERROR_DETAIL_SUBCODE, AS_ERROR_DETAIL_MESSAGE, and AS_ERROR_DETAIL_EXP_TRACE in as_subcode.h. Set the same field on default policies in as_config.policies to apply cluster-wide defaults.

At AS_ERROR_DETAIL_EXP_TRACE, the client does not decode the trace into a separate field. Instead, the server’s expression trace arrives as a ; exp_trace={...} suffix appended directly to err.message. See Expression traces for the trace shape.

See Server error details for behavior, operator caps, and coverage. Structured error details require Aerospike Database 8.2.0 or later and C client 7.6.2 or later. The Client matrix lists 7.6.2 as the paired C client release for Database 8.2.0.