Aerospike Database 8.2.0 Release Notes

September 29, 2026  |  Download

New in this version

• Support for Ubuntu 26.04 LTS
• Preview startup flag (--preview) replaces --experimental
• List join (8.2.0) — concatenates list-of-strings elements; inverse of string split
• Blob b64_encode (8.2.0) — encodes blob to string; pairs with string b64_decode
• Structured server error details such as subcodes, messages, and expression traces

Developer experience

• String operations: 35 server-side read, modify, and conversion functions using the Operate API and expressions. Uses Unicode codepoints for index positions. See the string operations overview and operations reference.

• UTF-8 validation at string operation boundaries: String operations reject invalid UTF-8 with AS_ERR_INVALID_ENCODING. Standard writes still accept it and trigger a rate-limited warning. See Upgrade to Database 8.2.0 and later.

• ICU regular expressions: String regex_compare and regex_replace, the Aerospike expression language (AEL) =~ match operator, and regexReplace() compile patterns with ICU syntax, not PCRE or legacy POSIX cmp_regex syntax. Unsupported constructs are rejected at parse time. Replace operations use ICU’s replacement dialect (capture references such as $1 and ${name}, $0, and \ escapes); an unresolvable $ fails the operation on any record the pattern matches, and is never evaluated on one it does not. Patterns that exceed ICU evaluation limits return AS_ERR_OP_NOT_APPLICABLE with AS_SUB_OPNOT_STRING_REGEX_LIMIT_EXCEEDED. See Regular expression syntax.

• Query optimizer: Database 8.2.0 adds a server-side query optimizer for automatic secondary index (SI) selection on AEL predicates.

  • Default behavior: A Developer SDK query with a where clause that finds no matching SI can fail with AS_ERR_SINDEX_NOT_FOUND (201) rather than reading every record, controlled per query or per Behavior by allowScansWithWhere. Queries without a where clause, background queries, and aggregations are unaffected.
  • Fallback option: Enable allowScansWithWhere to allow explicit fallback to primary index (PI) queries.
  • A query that carries no AEL and names no index runs against the primary index, as before. See Query optimizer.

• Unordered Map comparison in expressions: Expressions now support comparing unordered Maps, including equality comparisons. See Map comparison.

• Integer secondary index type name: Renamed the integer secondary index key type from numeric to integer for clarity. numeric is now deprecated but remains supported as an alias.

  • Usage: Specify integer with sindex-create and manage sindex create in asadm.
  • Existing indexes: No re-index required. Existing integer indexes continue to work.
  • API and command outputs:
    • sindex-list outputs type=integer when using v=v2 (v1 retains numeric for backward compatibility)
    • show sindex may still show numeric in the Bin Type column.
  • Client and deprecation behavior: Language client createIndex() APIs sending numeric on the wire will still be accepted. However, using numeric logs a warning and increments the deprecated_requests metric.

• Structured error details (Database 8.2.0 and later): Failed operations can now return extended error context based on a configurable verbosity level:

  • Level 1: Numeric subcode (scoped to parent status).
  • Level 2: Subcode + human-readable message.
  • Level 3: Subcode + message + expression trace (for expression failures).
  • Configuration: Opt-in per request via client policy (errorDetailVerbosity / error_detail_verbosity). Default is 0 (disabled), preserving existing application behavior.
  • Best Practice: Applications must dispatch error handling on the (status, subcode) pair, not subcode alone.
  • Coverage: Supported on single-record ops, batch (per-record), expressions, CDT, HLL, bitwise, string ops, transactions, and client-invoked UDFs.
  • Exclusions: Background UDF/operate jobs, batch-wide admission errors, and queries that fail after start.

Performance enhancements

• Wire compression (Enterprise Edition): Added Zstd compression for intra-cluster traffic to reduce cross-AZ (Availability Zone) network costs.
  • Supported traffic: Replica writes, partition migrations, and SMD full-sync messages.
  • Delta mode: Replica writes support delta encoding, transmitting only changed bytes against the prior record version
  • Configuration: Opt-in per transport and dynamically configurable without restarts. See Configure wire compression and Configure SMD wire compression.

Operations

• Improved memory over-configuration warning: The startup and dynamic-configuration memory best-practice check compares the configured maximum DRAM footprint, including indexes-memory-budget, in-memory data-size, and full max-write-cache and post-write-cache sizes, against the budget defined by stop-writes-sys-memory-pct, rather than comparing only in-memory data and index budgets to total system RAM. See Namespace memory budget.

• Wire compression metrics: Per-channel fabric byte counters, available in both editions, plus the Enterprise-only per-namespace replication and migration compression savings, delta-mode hit rates, and codec CPU percentages help you tune compression modes and levels. Query zstd-wire-stats for codec call counts and CPU; smd-info for SMD compression stats. Per-operation CPU percentages require enable-benchmarks-wire-compression. See the Metrics reference.

• Index checkpoint (Enterprise only, preview): Optional per-namespace durable copy of shared memory indexes for warm restart after a container replacement or host reboot. Enable with --preview index-checkpoint and per-namespace configuration. See Index checkpoint.

• SMD readiness on node join: A new or returning node completes its initial system metadata (SMD) sync before it accepts client or admin connections, and before it receives incoming record migrations. There is no configuration. See Upgrade instructions for rolling-upgrade behavior.

• Preview startup flag (--preview): Database 8.2.0 and later reject --experimental and require --preview to enable preview features by name. In this release, valid feature names are yaml-config (YAML configuration files) and index-checkpoint (index checkpoint). On Database 8.1.1 and 8.1.2, continue using --experimental for YAML configuration.

Breaking changes

CDT nesting depth limited to 64 levels

Starting with Aerospike Database 8.2.0, Lists and Maps support up to 64 levels of nesting. A top-level List or Map counts as level 1, and each nested List or Map adds one level. Keep collection values within this limit.

This change can affect data that predates this release when that data re-enters the server over the wire, such as:

• A client read-modify-write round trip on an existing List or Map nested deeper than 64 levels
• XDR shipping such a record to a destination running Database 8.2.0 or later
• Restoring a backup that was taken before the upgrade

The server checks the nesting depth of each List or Map value in a request: whole-bin writes, CDT operation values, and expression literals. It does not re-check values already stored, so an ordinary read of a List or Map stored deeper than 64 levels returns it unchanged.

Operation	Status code	What the client receives
Whole-bin write of a List or Map	AS_ERR_UNKNOWN (1)	list/map nested too deeply
CDT operation payload in an operate() command, such as list_append or map_put	AS_ERR_PARAMETER (4)	The same message, prefixed with the server’s handler name, for example list_append: list/map nested too deeply. A map_put returns map_add: invalid value - list/map nested too deeply, or invalid key when the key is the part nested deeper than 64 levels.
An expression that contains a List or Map literal deeper than 64 levels	AS_ERR_PARAMETER (4)	invalid filter expression in request (wording varies by request type). The expression fails to build, so no record is evaluated.
A Map passed directly as a CDT function argument in an expression, such as the value in MapExp.put	AS_ERR_OP_NOT_APPLICABLE (26) in an operate() call, AS_ERR_FILTERED_OUT (27) as a filter	The expression builds, then the Map operation refuses the value when the expression runs with map_add: invalid value - list/map nested too deeply.
An expression that reads a stored bin nested deeper than 64 levels	None	The expression evaluates against the stored bytes, which are not normalized to key order
A UDF that reads a stored bin nested deeper than 64 levels	None	nil, with no error to distinguish that bin from a missing one
An ordinary read of a stored bin nested deeper than 64 levels	None	The stored value, unchanged

The client receives the message text only when the request sets error detail verbosity to 2 or higher. Otherwise, the client receives the status code alone.

See Nesting depth limit to learn how depth is counted.

allow-unsafe-lua now defaults to false

Database 8.2.0.0 changes the default of mod-lua.allow-unsafe-lua from true to false, making Lua sandbox hardening the default. Hardened mode removes risky Lua globals (os, io, debug, dofile, loadfile, load, loadstring), blocks native .so and precompiled bytecode UDFs, and requires the lowercase .lua extension at registration.

Caution

Before upgrading, audit your registered UDFs against the migration checklist. A UDF that depends on the removed functions or module formats breaks after upgrade unless you set allow-unsafe-lua true first.

To keep the permissive behavior after upgrading, set mod-lua.allow-unsafe-lua to true and restart each node.

Note

Database 8.1.2.x, 8.0.0.x, 7.2.0.x, and 7.1.0.x are unaffected and continue to default to true.

See UDF security and sandbox hardening for the full behavior change and migration checklist.

Platform updates

• Database 8.2.0 adds support for Ubuntu 26.04 LTS, including OpenSSL 3.5 compatibility on that platform. Ubuntu 26.04 requires Database 8.2.0 or later.

• Database 8.2.0 build artifacts are not provided for Debian 12 (Bookworm). See Platform support and compatibility.

• Database 8.2.0 build artifacts are not provided for Ubuntu 22.04 LTS (Jammy Jellyfish). See Platform support and compatibility.

• On Ubuntu 24.04 and 26.04, install libcurl4t64. See Install on Linux, Install on Google Cloud, and Platform support and compatibility.

Upgrade instructions

You can upgrade directly to Database 8.2.0 from releases 7.1.0.x through 8.1.2.x.

• For upgrade instructions, see Upgrade or repair an Aerospike server.
• For special upgrade instructions, see Special upgrades and downgrades.

Rolling upgrades:

• Wire compression is opt-in and disabled by default. There is nothing to do at upgrade time.

  • Replica-write and SMD compression start only after every node in the cluster is Database 8.2.0 or later.
  • Migration compression can be used between two upgraded nodes during a rolling upgrade. Support is negotiated separately for each migration peer.

• SMD readiness (new in Database 8.2.0):

  • The wait arms only when every node in the cluster is Database 8.2.0 or later, so during a rolling upgrade only the last node you upgrade waits.
  • While a node waits, client requests, asinfo, and asadm against that node time out rather than being refused. The rest of the cluster defers its incoming migrations until it is ready.
  • The node is ready when its log shows initial SMD sync done for cluster key <key>. A still waiting for initial SMD sync warning repeating every 10 seconds is expected until then. See System metadata readiness on node join.

Reference and error code updates

The following tables outline the latest reference updates for configurations, info commands, metrics server logs, and error messages.

Configuration updates

Item	Action	Notes
replication-compression-mode	added	Per-namespace. Controls replica write compression. Values: none, zstd, or delta-zstd. Default: none. Enterprise only.
replication-compression-level	added	Per-namespace. Zstd compression level for replica writes. Range: -10 to 22. Default: 1. Enterprise only.
migrate-compression-mode	added	Per-namespace. Controls partition migration compression. Values: none or zstd. Default: none. Independent of replication compression. Enterprise only.
migrate-compression-level	added	Per-namespace. Zstd compression level for migrations. Range: -10 to 22. Default: 1. Enterprise only.
smd-compression-mode	added	Service context. Controls SMD full-sync compression. Values: none or zstd. Default: none. Enterprise only.
smd-compression-level	added	Service context. Zstd compression level for SMD sync. Range: -10 to 22. Default: 1. Enterprise only.
enable-benchmarks-wire-compression	added	Service context. Enables per-operation codec CPU accounting for wire compression benchmarking. Default: false. Accepted in Community Edition, where the compression modes it profiles are unavailable and the counters read zero.
index-checkpoint-path	added	Per-namespace. Absolute path to the checkpoint directory. Enables checkpoint-save and automatic hydrate on start. Requires --preview index-checkpoint. Enterprise only.
index-checkpoint-threads	added	Per-namespace. Worker threads for checkpoint save and hydrate. Range: 1–16. Enterprise only.
index-checkpoint-compression	added	Per-namespace. Compress checkpoint blocks on write. Default: true. Enterprise only.
error-details-max-verbosity	added	Service context. Caps what clients can receive: off, codes, messages, all. Default: all. Effective verbosity = min(client-requested, server-max).
skip-checkpoint	added	Per-namespace. Excludes the namespace from the node-wide index checkpoint. Use to opt out a namespace that would otherwise be checkpointed. Has no effect unless index-checkpoint-path is set. Dynamic. Requires --preview index-checkpoint. Enterprise only.
allow-unsafe-lua	modified	mod-lua context. Default changed from true to false, enabling Lua sandbox hardening by default. See Breaking changes and UDF security and sandbox hardening.

Info command updates

Item	Action	Notes
zstd-wire-stats	added	Per-operation wire-compression codec call counts, CPU nanoseconds, and CPU percentages. CPU fields require enable-benchmarks-wire-compression. Enterprise only.
smd-info	extended	Adds compression_hit_pct, compression_bytes_saved, and compression_fallbacks for SMD wire compression. Enterprise only.
sindex-create	extended	type=integer is the preferred key type name for integer bins. type=numeric is deprecated but remains functional.
sindex-list	extended	Optional v parameter: v1 (default) reports type=numeric; v=v2 reports type=integer.
checkpoint-save	added	Writes an index checkpoint and shuts down the node. Requires the index-checkpoint preview feature. Enterprise only.
checkpoint-status	added	Reports index checkpoint progress per configured namespace. Enterprise only.

Metrics updates

Item	Action	Notes
index_shmem_alloc_bytes	added	Shared memory allocated for the namespace’s primary index arena. Enterprise only.
index_shmem_tail_bytes	added	Untouched space in the newest shared-memory primary-index stage. Enterprise only.
index_pmem_alloc_bytes	added	Persistent memory allocated for the namespace’s primary index arena. Enterprise only.
index_pmem_tail_bytes	added	Untouched space in the newest persistent-memory primary-index stage. Enterprise only.
set_index_alloc_bytes	added	Memory allocated for the namespace’s set indexes.
sindex_shmem_alloc_bytes	added	Shared memory allocated for the namespace’s secondary index arena. Enterprise only.
sindex_shmem_tail_bytes	added	Untouched space in the newest shared-memory secondary-index stage. Enterprise only.
sindex_pmem_alloc_bytes	added	Persistent memory allocated for the namespace’s secondary index arena. Enterprise only.
sindex_pmem_tail_bytes	added	Untouched space in the newest persistent-memory secondary-index stage. Enterprise only.
sindex_flash_alloc_bytes	added	Mount space allocated for the namespace’s secondary index arena. Enterprise only.
sindex_flash_tail_bytes	added	Untouched space in the newest flash secondary-index stage. Enterprise only.
process_rss_bytes	added	Resident set size of the asd process.
cgroup_memory_used_bytes	added	Memory charged to the server’s control group (cgroup).
cgroup_memory_limit_bytes	added	Memory limit of the server’s control group.
fabric_rw_bytes_sent	added	Post-compression bytes sent on the replication fabric channel.
fabric_rw_bytes_received	added	Post-compression bytes received on the replication fabric channel.
fabric_meta_bytes_sent	added	Bytes sent on the metadata fabric channel.
fabric_meta_bytes_received	added	Bytes received on the metadata fabric channel.
fabric_ctrl_bytes_sent	added	Bytes sent on the control fabric channel.
fabric_ctrl_bytes_received	added	Bytes received on the control fabric channel.
fabric_bulk_bytes_sent	added	Bytes sent on the bulk fabric channel (migrations and large transfers).
fabric_bulk_bytes_received	added	Bytes received on the bulk fabric channel.
wire_comp_cpu_pct	added	Combined CPU percentage for all wire-compression codec operations. Requires enable-benchmarks-wire-compression. Enterprise only.
wire_comp_make_patch_cpu_pct	added	CPU percentage for delta-patch generation. Requires enable-benchmarks-wire-compression. Enterprise only.
wire_comp_apply_patch_cpu_pct	added	CPU percentage for delta-patch application on replicas. Requires enable-benchmarks-wire-compression. Enterprise only.
wire_comp_compress_cpu_pct	added	CPU percentage for plain Zstd compression. Requires enable-benchmarks-wire-compression. Enterprise only.
wire_comp_decompress_cpu_pct	added	CPU percentage for Zstd decompression. Requires enable-benchmarks-wire-compression. Enterprise only.
repl_wire_compression_bytes_saved	added	Cumulative replication payload bytes kept off the wire. Enterprise only.
repl_wire_compression_fallbacks	added	Replication writes that the replica rejected and the partition master retransmitted uncompressed. Enterprise only.
repl_wire_compression_not_beneficial	added	Replication codec calls where compression did not reduce payload size. Enterprise only.
repl_wire_compression_delta_attempts	added	Delta-mode replication compression attempts. Enterprise only.
repl_wire_compression_delta_hits	added	Delta-mode replication writes that used a patch smaller than the full record. Enterprise only.
repl_wire_compression_delta_hit_pct	added	Delta-mode replication hit percentage. Enterprise only.
repl_wire_compression_delta_not_beneficial	added	Delta-mode attempts where neither patch nor full compression reduced size. Enterprise only.
repl_wire_compression_delta_apply_device_reads	added	Device reads performed while applying a delta patch on replicas. Enterprise only.
repl_wire_compression_delta_reject_apply	added	Delta patches rejected during application. Enterprise only.
repl_wire_compression_delta_reject_no_record	added	Delta patches rejected because the prior record version was unavailable. Enterprise only.
repl_wire_compression_delta_reject_version	added	Delta patches rejected due to version mismatch. Enterprise only.
repl_wire_compression_delta_reject_other	added	Delta patches rejected for other reasons. Enterprise only.
migrate_wire_compression_bytes_saved	added	Cumulative migration payload bytes kept off the wire. Enterprise only.
migrate_wire_compression_fallbacks	added	Migration payloads that fell back to uncompressed transfer. Enterprise only.
migrate_wire_compression_not_beneficial	added	Migration codec calls where compression did not reduce payload size. Enterprise only.
compression_hit_pct	added	Percentage of SMD full-sync messages that compressed to something smaller and were sent compressed. Returned by smd-info. Enterprise only.
compression_bytes_saved	added	Cumulative SMD full-sync payload bytes kept off the wire. Returned by smd-info. Enterprise only.
compression_fallbacks	added	SMD full-sync messages sent uncompressed, either too small to compress or where compression offered no saving. Returned by smd-info. Enterprise only.

Server log updates

Log message	Added or Modified	Notes
{NAMESPACE} Disk encryption does not imply encrypted data on the wire. TLS encryption should be enabled when encryption-at-rest is enabled.	added	Logged at WARNING when a namespace has encryption-at-rest configured but any TLS endpoint (service, admin, fabric, or heartbeat) is not. Advisory only — does not affect startup. Enterprise only. See TLS configuration.

Error code updates

Error message	Added or Modified	Notes
AS_ERR_PARAMETER (4)	modified	For string operations: invalid UTF-8 in an operation argument (needle, pattern, pad string), invalid regex syntax or flags, malformed context path, or a modify result estimated over 8 MiB. See Error subcodes.
AS_ERR_UNAVAILABLE (11)	modified	Subcodes for balance/replica unavailability. See Error subcodes.
AS_ERR_INCOMPATIBLE_TYPE (12)	modified	For string operations: operation applied to a non-String bin.
AS_ERR_RECORD_TOO_BIG (13)	modified	For string modify operations: result passes the 8 MiB per-operation cap but exceeds max-record-size.
AS_ERR_UNSUPPORTED_FEATURE (16)	modified	Subcodes for transactions/strong consistency and generic unsupported. See Error subcodes.
AS_ERR_BIN_NOT_FOUND (17)	modified	Subcodes for HLL and string-value cases. See Error subcodes.
AS_ERR_BIN_NAME (21)	modified	Subcode for bin-count limit on the UDF path. See Error subcodes.
AS_ERR_FORBIDDEN (22)	modified	Subcodes for XDR filter blocks, stop-writes, truncation, clock skew, and durability violations. See Error subcodes.
AS_ERR_OP_NOT_APPLICABLE (26)	modified	For string operations: numeric parse failure or overflow, to_string on non-UTF-8 blob, invalid base64, or regex pattern exceeded complexity limits (AS_SUB_OPNOT_STRING_REGEX_LIMIT_EXCEEDED). See Error subcodes.
AS_ERR_FILTERED_OUT (27)	modified	At verbosity 3, can include an expression trace (no subcode). See Expression traces.
AS_ERR_INVALID_ENCODING (29)	modified	String bin contains invalid UTF-8 when a string operation runs. Repair the bin before retrying. See Repair legacy String bins.
AS_ERR_MRT_BLOCKED (120)	modified	Subcodes for lock/TID (Transaction ID)/expiry cases. See Error subcodes.
AS_ERR_SINDEX_NOT_FOUND (201)	modified	Also returned when a query carries a where clause, no secondary index matches it, and allowScansWithWhere is false. See Query optimizer.

Known issues

Known issues for 8.2.0

Documentation updates

• String examples
• String operations reference
• Regular expression syntax
• String operations reference
• Query optimizer
• Secondary index queries
• Namespace memory budget
• Metrics reference
• Index checkpoint
• Warm restart
• Quiesce a node
• Configure Aerospike Database
• Aerospike Daemon CLI options
• Configure wire compression
• Configure SMD wire compression
• System metadata readiness on node join
• Server error details
• Error subcodes

Complete list of changes

ID	Description
AER-6920	(SINDEX) Deprecated the ‘numeric’ sindex type in favor of ‘integer’.
AER-6931	(PACKAGING) Add support for Ubuntu 26.04 LTS (Resolute Raccoon).
AER-6932	(KVS) Return optional structured error details to clients.
AER-6933	(KVS) Add a Unicode string operations API for expressions and bin operations.
AER-6934	(CONFIGURATION) Warn at startup when encryption-at-rest is enabled without TLS.
AER-6935	(EXPRESSIONS) Improve expression performance by reading each referenced bin from the record only once.
AER-6936	(CONFIGURATION) Replace --experimental startup flag with --preview for explicit per-feature opt-in. See Aerospike Daemon CLI options.
AER-6940	(SMD) New and returning cluster nodes now wait for SMD sync before accepting client connections.
AER-6941	(EXPRESSIONS) Add the Aerospike Expression Language (AEL) for authoring filter expressions as text.
AER-6942	(STATS) Add index/sindex allocation, cgroup, and process-RSS memory metrics.
AER-6943	(QUERY) Add a server-side query optimizer for automatic index selection. See Query optimizer.
AER-6945	(FABRIC) Add optional Zstandard wire compression for replication, migration, and SMD synchronization.
AER-6948	(FABRIC) Cache-line-isolated hash-table locks cut hot-path contention and long-tail latency.
AER-6952	(CLUSTERING) Fix ‘recluster’ failing after an aborted exchange round.
AER-6956	(KVS) Add an optional index checkpoint for warm-restart-equivalent startup after pod replacement. See Index checkpoint.
AER-6957	(UDF) CVE-2026-63662 Bounds-check msgpack deserialization.
AER-6959	(KVS) CVE-2026-71423 Fix a crash when extracting a zero-length bytes element from a list or map.
AER-6960	(CDT) CVE-2026-71419 Fix a heap overflow when writing a persist-index list or map of wide-encoded integers.
AER-6961	(SINDEX) Fix stray leading ’;’ in sindex-list response for namespaces with only set indexes.
AER-6962	(EXPRESSIONS) Fix an expression write operation reporting success when it declined to delete a bin.
AER-6964	(XDR) Fix corrupted xdr-dc-state output for namespace names of seven or more characters.
AER-6965	(MEMORY) Fixed memory leaks in the secondary index definition hash, histogram teardown, and allocator self-check.
AER-6966	(EXPRESSIONS) Fixed INF/WILDCARD markers and non-minimal msgpack encodings in list or map expression literals being rejected with PARAMETER_ERROR.
AER-6967	(EXPRESSIONS) Comparisons involving unordered maps now return a result instead of an error.
AER-6968	(UDF) Default allow-unsafe-lua to false.
AER-6969	(MEMORY) Extended the memory best-practice check to count write caches and use ‘stop-writes-sys-memory-pct’.
AER-6971	(MASKING) Fix redact divide-by-zero crash on an empty string value.
AER-6972	(EXPRESSIONS) Fixed a node crash when a map literal in an expression call parameter was not in canonical order.