Error handling

If an error occurs as a result of the database operation, an AerospikeError returns.

The AerospikeError ResultCode field describes the exact cause of the error given by the Aerospike server.

Errors can also occur internally on the client side, either originating from the client code or from within the go stdlib. These errors are not converted to an AerospikeError instance unless they are io.Timeout errors.

Server error details

Aerospike Database 8.2.0 and later can return a numeric subcode, a message, and, at the highest verbosity, an expression trace when an expression fails to build. The Aerospike Go client 8.9.0 and later supports reading those details. Enable them by setting ErrorDetailVerbosity (a plain int, default 0) on BasePolicy, which batch and other command policies inherit, then read the subcode from the returned *as.AerospikeError:

policy := as.NewPolicy()
policy.ErrorDetailVerbosity = 2

record, err := client.Get(policy, key)
if err != nil {
    if ae, ok := err.(*as.AerospikeError); ok {
        fmt.Printf("status=%s subcode=%d message=%s\n",
            ae.ResultCode, ae.SubCode, ae.ServerMessage)
    }
}

ErrorDetailVerbosity is out-of-range tolerant: the client clamps values below 0 up to 0 and above 3 down to 3 before sending the request. AerospikeError.SubCode (types.SubCode) is the numeric subcode; dispatch on the (ResultCode, SubCode) pair, never the subcode alone, and see Error subcodes. ExpTrace (*ExpressionTrace) carries a verbosity-3 expression trace on expression build-failure paths, with Outcome values ExpTraceOutcomeFault, ExpTraceOutcomeFalse, and ExpTraceOutcomeAbsent; see Expression traces for the trace shape. BatchRecord carries the same fields per row.

See Server error details for verbosity levels, coverage, and operator caps, and best practices for when to enable this in production.