---
title: "Error subcodes"
description: "Reference for Aerospike Database error subcodes returned with structured error details in Database 8.2.0."
---

# Error subcodes

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

This page describes error subcodes that disambiguate overloaded top-level [error codes](https://aerospike.com/docs/database/reference/error-codes). Each subcode integer is meaningful only together with its parent status.

## Applies to

-   Aerospike Database 8.2.0 and later
-   A client library that exposes error details (see [Server error details](https://aerospike.com/docs/database/reference/error-details))

## Audience

-   Developers who dispatch on `(status, subcode)` pairs
-   Operators cross-referencing failures against server behavior

Constant names follow the server’s naming, and this page is the authoritative catalog. Client libraries expose the same values under their own constant names, for example the `SubCode` class in the Java client or [`as_subcode.h`](https://aerospike.com/apidocs/c/db/d87/group__as__subcode.html) in the C client. A client’s catalog can lag the server’s, so where a client constant and this page disagree, this page is correct. See the error-handling page for your client.

Subcode values are stable: once published, an integer never changes meaning, and retired values are not reused.

## `AS_ERR_PARAMETER` (4)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_PARAM_TTL_INVALID` | Record TTL exceeds the 10-year protocol maximum |
| 2 | `AS_SUB_PARAM_BITS_OFFSET_OUT_OF_RANGE` | Bits op offset past the proto size cap |
| 3 | `AS_SUB_PARAM_BITS_SIZE_OUT_OF_RANGE` | Bits op size out of range |
| 4 | `AS_SUB_PARAM_BITS_RESIZE_EXCEEDED` | Bits resize, insert, or remove would exceed the maximum blob size |
| 5 | `AS_SUB_PARAM_BIN_COUNT_TOO_LARGE` | Write would exceed per-record bin-count limit |
| 6 | `AS_SUB_PARAM_STRING_OP_PARAMS_INVALID` | String op parameters malformed or inconsistent |
| 7 | `AS_SUB_PARAM_STRING_OP_INVALID` | Unreadable string op code, or an op used in the wrong read/modify direction |
| 8 | `AS_SUB_PARAM_STRING_CTX_MALFORMED` | String operation context is malformed |
| 9 | `AS_SUB_PARAM_STRING_INDEX_OUT_OF_BOUNDS` | String op index or range out of bounds |
| 10 | `AS_SUB_PARAM_STRING_REGEX_INVALID` | Regular expression is not valid ICU syntax, or failed to compile |
| 11 | `AS_SUB_PARAM_STRING_UTF8_INVALID` | String argument is not valid UTF-8 |

## `AS_ERR_UNAVAILABLE` (11)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_UNAVAIL_INITIAL_BALANCE_UNRESOLVED` | Cluster still resolving initial partition balance |
| 2 | `AS_SUB_UNAVAIL_REPLICA_UNAVAILABLE` | Needed replica unavailable (possible partition split) |
| 3 | `AS_SUB_UNAVAIL_NODE_SHUTTING_DOWN` | Node is shutting down and leaving the cluster |

## `AS_ERR_UNSUPPORTED_FEATURE` (16)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_UNSUPP_FEAT_MRT_REQUIRES_STRONG_CONSISTENCY` | Multi-record transaction (MRT) used against a namespace without strong consistency |
| 2 | `AS_SUB_UNSUPP_FEAT_GENERIC` | Requested feature unsupported in this context |

## `AS_ERR_BIN_NOT_FOUND` (17)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_BIN_NOT_FOUND_HLL_CANNOT_CREATE_WITH_OP` | HLL op cannot create the bin it was given |

## `AS_ERR_BIN_NAME` (21)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_BIN_NAME_COUNT_TOO_LARGE` | Record is at or over the UDF bin-count limit (UDF path) |

## `AS_ERR_FORBIDDEN` (22)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_FORBID_XDR_FILTER_BLOCKED` | Write blocked by XDR ship filter |
| 2 | `AS_SUB_FORBID_SET_COUNT_STOP_WRITES` | Set-level record-count stop-writes |
| 3 | `AS_SUB_FORBID_SET_SIZE_STOP_WRITES` | Set-level size stop-writes |
| 4 | `AS_SUB_FORBID_CLOCK_SKEW_STOP_WRITES` | Writes stopped due to cluster clock skew |
| 5 | `AS_SUB_FORBID_REPLACE_CONFLICT_RESOLVING` | REPLACE forbidden while resolving conflicts |
| 6 | `AS_SUB_FORBID_TRUNCATED` | Set or namespace mid-truncate |
| 8 | `AS_SUB_FORBID_DURABILITY_VIOLATION` | Non-durable delete forbidden |

Subcodes 7 and 9 are retired and not reused.

## `AS_ERR_OP_NOT_APPLICABLE` (26)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_OPNOT_CDT_INDEX_OUT_OF_BOUNDS` | List/map index out of range. Also raised for an out-of-range rank on an ordered list |
| 2 | `AS_SUB_OPNOT_CDT_RANK_OUT_OF_BOUNDS` | Requested rank past the population, in either direction, on a single-result op |
| 3 | `AS_SUB_OPNOT_CDT_BOUNDED_LIST_OVERFLOW` | Insert into a bounded list at an index past the end |
| 4 | `AS_SUB_OPNOT_HLL_INDEX_BITS_UNSET` | HLL op must create the bin but the op omitted `index_bits` |
| 5 | `AS_SUB_OPNOT_HLL_CANNOT_REDUCE_INDEX_BITS` | Union cannot reduce `index_bits` without fold |
| 6 | `AS_SUB_OPNOT_HLL_CANNOT_REDUCE_MINHASH_BITS` | Union cannot reduce minhash bits without fold |
| 7 | `AS_SUB_OPNOT_HLL_CANNOT_FOLD_MINHASH` | Fold blocked because sketch carries minhash |
| 8 | `AS_SUB_OPNOT_HLL_FOLD_INDEX_BITS_TOO_LARGE` | Fold target `index_bits` greater than current. Folding to the current value is allowed |
| 9 | `AS_SUB_OPNOT_HLL_INTERSECT_MINHASH_MISMATCH` | Intersect inputs have mismatched minhash params |
| 10 | `AS_SUB_OPNOT_STRING_CONVERSION_FAILED` | String conversion, for example to a number, failed |
| 11 | `AS_SUB_OPNOT_STRING_UTF8_INVALID` | Stored value is not valid UTF-8 for this string op |
| 12 | `AS_SUB_OPNOT_STRING_REGEX_LIMIT_EXCEEDED` | Regular expression exceeded the engine resource budget |
| 13 | `AS_SUB_OPNOT_STRING_B64_INVALID` | String is not valid Base64 |

## `AS_ERR_MRT_BLOCKED` (120)

| Subcode | Constant | Summary |
| --- | --- | --- |
| 1 | `AS_SUB_MRT_BLOCKED_RECORD_LOCKED` | Record locked by another MRT |
| 2 | `AS_SUB_MRT_BLOCKED_ID_MISMATCH` | Op belongs to a different MRT than the lock holder |

## Statuses without subcodes

Many statuses are already specific enough that the server emits no subcode. For example, `AS_ERR_BIN_EXISTS` (6), `AS_ERR_GENERATION` (3), and `AS_ERR_RECORD_TOO_BIG` (13). For those failures, rely on the top-level code and any message text at verbosity `2`.

`AS_ERR_FILTERED_OUT` (27) also carries no subcode. At verbosity `3`, a filtered-out single-record operation can instead include an expression trace explaining which part of the filter rejected the record. See [Expression traces](https://aerospike.com/docs/database/reference/error-details#expression-traces).

## Related pages

-   [Server error details](https://aerospike.com/docs/database/reference/error-details), enable and read structured errors
-   [Error codes](https://aerospike.com/docs/database/reference/error-codes), top-level codes
-   [`error-details-max-verbosity`](https://aerospike.com/docs/database/reference/config#service__error-details-max-verbosity), operator cap on message verbosity
-   [C client API: Error detail constants](https://aerospike.com/apidocs/c/db/d87/group__as__subcode.html)