# NATS v2.12.3

2025-12-17 · [Original release notes](https://github.com/nats-io/nats-server/releases/tag/v2.12.3) · [Full summary](https://ratatosk.io/en/releases/nats/v2.12.3)

Security 4 · Breaking changes 6 · Important fixes 27 · Enhancements 13 · Dependency updates 8 · Other changes 11

## Check before upgrading

### Upgrade guide

- **2.12 upgrade guide for users on 2.11.x**
  > Refer to the [2.12 Upgrade Guide](https://docs.nats.io/release-notes/whats_new/whats_new_212) for backwards compatibility notes with 2.11.x.

  - GC thresholds controlled by `GOMEMLIMIT`: The note says tuning `GOMEMLIMIT` may be appropriate based on available system memory or, in Kubernetes, memory reservations.
  - Stream state files rebuilt after downgrade: On the first restart after downgrading from v2.12 to v2.11, all stream message blocks are rescanned, which can increase CPU use and delay the restarted node reporting healthy. This does not cause data loss.

## Security (4)

### [medium] WebSocket compression-bomb memory use fixed

- 2026-02-23 · [Security advisory GHSA-qrvq-68c2-7grw published after the release](https://github.com/nats-io/nats-server/security/advisories/GHSA-qrvq-68c2-7grw)
- Affects: WebSocket connections receiving compressed frames
- [CVE-2026-27571](https://www.cve.org/CVERecord?id=CVE-2026-27571), [GHSA-qrvq-68c2-7grw](https://github.com/nats-io/nats-server/security/advisories/GHSA-qrvq-68c2-7grw)

Previously, decompressing a highly compressed frame could create a very large buffer before the server rejected it for exceeding the maximum payload size, risking excessive memory use and server termination. Decompression now stops at the configured maximum payload size, or the default maximum if none is specified, and returns `ErrMaxPayload`.

> - WebSocket connections will now correctly limit the buffer size during decompression (#7625, thanks to Pavel Kokout at Aisle Research)

Security advisory:

> This was fixed in the v2.11 series with v2.11.12 and in the v2.12 series with v2.12.3.

https://github.com/nats-io/nats-server/security/advisories/GHSA-qrvq-68c2-7grw

### Implicit `$MQTT.` subject permissions for MQTT clients and non-client connections

- Affects: MQTT clients and non-client connections, including routes and leaf connections

Previously, configured subscribe permissions needed an explicit allow for the `$MQTT_sub.` prefix used by JetStream consumer subscriptions. These connections can now publish and subscribe on `$MQTT.`-prefixed subjects without an allow entry, but `deny` ACLs still apply; regular NATS core clients receive no implicit allowance.

> - Permissions to `$MQTT.` subscriptions are now handled implicitly, with the exception of `deny` ACLs which still permit restriction (#7637)

### TLS cipher-suite selection updated

- Affects: TLS connections relying on insecure or newly available cipher suites (Inferred)

New cipher suites from `crypto/tls` are added automatically, while insecure suites are disabled by default unless `allow_insecure_cipher_suites` is enabled.

> Use cipher suites from crypto/tls : New cipher suites are now automatically added. Additionally, insecure cipher suites are disabled by default, but can be allowed when enabling allow_insecure_cipher_suites .

https://docs.nats.io/release-notes/whats_new/whats_new_212

### Connection logging gains identity details

- Affects: client-connection-related and connection-closed logs (Inferred)

Client-connection-related logs include the account name and user; connection-closed logs include the remote server name.

> Account name and user logging: Any logging related to a client connection, for example when reaching maximum connections or for authentication errors, will now include the account name and user of that client connection. Connection closed logging now includes the remote server name.

https://docs.nats.io/release-notes/whats_new/whats_new_212

## Breaking changes (6)

### JetStream meta layer waits for quorum before replying to peer-remove requests

- Affects: setups issuing peer-remove requests handled by the JetStream meta layer (Inferred)

Previously, the meta leader could report success before peer removal reached quorum, leaving the cluster unchanged while users or automated processes believed its size had shrunk.

> - The meta layer will now only respond to peer remove requests after quorum has been reached (#7581)

### Filestore removal accounting follows disk operations

- Affects: filestore message removal (Inferred)

Previously, failed tombstone writes could be silent, while failed secure erasure could leave accounting ahead of on-disk state. Tombstone-write failures now surface as errors.

> - The filestore now will process message removal on disk before updating accounting, which improves error handling (#7595, #7601)

### Filestore and consumer operations propagate message-block load errors

- Affects: filestore and consumer operations that load uncached message blocks (Inferred)

When loading an uncached message block fails, affected operations now return or propagate the error instead of continuing.

> - Improved error handling within the loading of message blocks if not already cached (#7631)

### MQTT maximum payload limit enforced

- Affects: MQTT clients with a configured maximum payload size (Inferred)

Previously, an MQTT publish whose total NATS message size exceeded the maximum payload size could be silently accepted instead of failing the connection check. Such publishes now fail that check.

> - The maximum payload size is now correctly enforced for MQTT clients (#7555, thanks to @yixianOu)

### Raft now blocks concurrent membership changes

- Affects: Setups performing Raft membership changes, including JetStream peer-removal operations

Previously, a new membership change could be proposed while another was still in progress. Now, the leader drops a concurrent change, and JetStream peer removal can return a member-change-in-progress error.

Evidence: “A simple approach based to avoid concurrent membership changes. The leader simply drops a membership change if there is another membership change in progress. A membership is in progress if it has been proposed, but not committed yet.” https://github.com/nats-io/nats-server/pull/7565

> - Raft will no longer allow multiple membership changes to take place concurrently (#7565, #7609)

### More reliable replicated in-memory stream recovery

- Affects: replicated in-memory streams

After all but one server is restarted, the stream’s data can reliably catch up. During that recovery, every server replicating the stream must be available, not just a quorum.

> -
> Stream/consumer scaleup and reset disk/state protection: The server now has better protections against leader elections based on empty state. This also improves reliability of replicated in-memory streams. Usually a quorum of servers needs to be online and contain data. Now all but one server can be restarted and the in-memory stream's data can reliably be caught back up. However, during such a scenario all servers involved with replication of that stream will need to be available, not just what's needed for quorum. This lets the servers decide the best course of action to preserve all data.

https://docs.nats.io/release-notes/whats_new/whats_new_212

## Important fixes (27)

### Invalid subject filter matching fixed

- Affects: invalid subject filters containing a non-terminating full wildcard

The invalid filter `foo.>.bar` could unexpectedly match `bar` instead of producing zero matches. It no longer matches `bar`.

> - Invalid subject filters containing non-terminating full wildcard no longer produce unexpected matches (#7585)

### Filestore whole-block purges now update subject and schedule tracking

- Affects: filestores that purge whole message blocks

When whole message blocks were purged, including to enforce limits, per-subject state could remain unadjusted and scheduled-message metadata could be left behind.

> - When purging whole message blocks, the subject tracking and scheduled messages are now updated correctly (#7593)

### Raft quorum counting ignores responses from removed peers

- Affects: Raft groups with peer membership

When Raft received an append-entry response from a node removed from peer membership, that response could incorrectly count toward quorum without an error.

> - Raft will no longer count responses from peer-removed nodes towards quorum (#7589)

### Filestore pending-write loss fixed

- Affects: filestores configured with `AsyncFlush`

A sufficiently long process pause coinciding with `syncBlocks` at the `sync_interval` could leave pending writes lost. `syncBlocks` now flushes pending writes and avoids closing a block file descriptor while writes are pending, preventing that loss.

> - The filestore will no longer unexpectedly lose writes when `AsyncFlush` is enabled after a process pause (#7594)

### Raft quorum counting checks leader membership for implicit acknowledgments

- Affects: Raft groups with a leader outside the membership (Inferred)

Previously, quorum calculations could count the leader’s implicit acknowledgment even when the leader was no longer a member.

> - Raft quorum counting has been refactored so the implicit leader ack is now only counted if still a part of the membership (#7600)

### Raft peer state now persists immediately on removal

- Affects: Raft peer removal through `ProposePeerRemove`

Previously, a leader that removed a peer through `ProposePeerRemove` and then restarted could reload stale peer and quorum information and forget committed membership changes.

> - Raft now writes the peer state immediately when handling a peer-remove to ensure the removed peers cannot unexpectedly reappear after a restart (#7602)

### Replicated stream discard-policy desynchronization fixed

- Affects: replicated streams configured with `DiscardNewPerSubject` and `MaxMsgsPerSubject`

During snapshot catch-up, if a message was deleted after the snapshot and a client repeatedly published to its subject while the discard policy blocked it, a catching-up follower could store a different message at that sequence and diverge from the other servers. The leader now rejects messages that fail the discard policy before proposing them to followers, reducing this chance of desynchronization.

> - The `DiscardNewPerSubject` retention policy is now enforced by the leader before proposing rather than by individual replicas, reducing the potential for stream desync (#7607)

### Raft rejects removal of the last peer

- Affects: Raft peer-removal operations targeting the last remaining peer

Previously, the removal could be accepted and leave the cluster in an invalid state; now the peer remains in membership.

> - Raft will no longer allow peer-removing the one remaining peer (#7610)

### Filestore message loss during large compactions fixed

- Affects: Filestore blocks undergoing compaction

When compaction reclaimed over half of a file's storage, a hard kill after truncation but before the compacted bytes were fully written could lose messages. The compacted bytes are now written to a separate file before it atomically replaces the original.

> - Compactions that reclaim over half of the available space now use an atomic write to avoid losing messages if killed (#7627)

### Raft peer set no longer readmits removed leaders

- Affects: Raft groups undergoing peer removal and leadership transfer

When a heartbeat occurred after peer removal was committed but before leadership transfer was processed, the follower could recreate the removed leader in its peer set; it no longer does so in that sequence.

> - Raft groups should no longer readmit a previously removed peer if a heartbeat occurs between the peer removal and the leadership transfer (#7649)

### Replicated file-based stream snapshot desynchronization fixed

- Affects: replicated file-based streams

A message removal during a stream snapshot could desynchronize the stream, and removal was rejected while the snapshot was in progress.

> - Potential stream desyncs that could happen during stream snapshotting have been fixed (#7655)

### Corrupted MQTT retained-message cache bodies fixed

- Affects: clustered MQTT deployments with retained-message caching

When S-2 had cached a retained message after a matching MQTT subscription started, a newer retained message for the same subject from S-1 could leave extra `\r\n` or random data in the cached body. The new body is copied into the cache, and trailing `\r\n` is stripped.

> - A bug which could corrupt retained messages in clustered deployments has been fixed (#7622)

### MQTT QoS2 message delivery after restart fixed

- Affects: MQTT QoS2 subscriptions

When a subscription was restarted after a server restart, it received neither messages persisted while offline nor new incoming messages. It can now retrieve the persisted messages and receive new ones.

> - A bug where QoS2 messages could not be retrieved after a server restart has been fixed (#7643)

### Cross-account MQTT retained messages with subject transforms fixed

- Affects: MQTT retained-message streams sourced from another account with a subject transform

During recovery, topics and subjects are recreated from the stream message subject with the prefix removed.

> - Retained messages will now work correctly even when sourced from a different account and has a subject transform (#7636)

### Duplicate `@<subject>` suffix in JetStream acknowledgements fixed

- Affects: JetStream setups with gateway and route or leaf traffic and captured stream imports for local subscriptions

When an acknowledgement reply crossed a gateway, a captured stream import was used for a local subscription, and the reply then went over a route or leaf, the duplicate suffix caused a protocol error.

> - A protocol error caused by an invalid transform of acknowledgement reply subjects when originating from a gateway connection has been fixed (#7579)

### JetStream snapshot processing no longer panics on missing assignments or nodes

- Affects: JetStream snapshot processing for streams with missing assignments or nodes

It returns `errCatchupStreamStopped` instead of panicking.

> - A panic when processing snapshots with missing nodes or assignments has been fixed (#7588)

### Sequence recovery fixed for almost-empty Filestore streams

- Affects: almost-empty Filestore streams compacted or purged to sequence 2

If the server was hard killed after compaction or purge but before writing a tombstone, the sequence could not be recovered. The tombstone is now written to allow recovery in this situation.

> - Tombstones are now correctly written for recovering the sequences after compacting or purging an almost-empty stream to seq 2 (#7627)

### Filestore empty-block overwrite fixed

- Affects: filestore streams

After `SkipMsg(seq)`, `Compact(seq)`, and `SkipMsg(seq+1)`, another `SkipMsg(seq+1)` on the empty block could overwrite data at the file head, making the on-disk file appear corrupted and logging `indexCacheBuf corrupt record state`. That sequence no longer overwrites the block at the wrong offset or produces the corruption error.

> - Combining skip sequences and compactions will no longer overwrite the block at the wrong offset, correcting a `corrupt record state` error (#7627)

### Disjoint majorities from Raft peer addition fixed

- Affects: Raft groups adding peers during a partition

During a partition, adding a peer could leave the Raft group with disjoint majorities.

> - Add peer operations to Raft can no longer result in disjoint majorities (#7632)

### Filestore compaction now corrects stale sequences and deletion-map entries

- Affects: Filestore message blocks undergoing compaction

Compaction could leave `mb.last.seq` too high and retain deleted tail entries in `mb.dmap` after the last sequence moved down, causing index mismatches that led to “no idx present” errors and a reload. It now updates the last sequence and cleans up tail deletions as needed.

> - Filestore compaction now correctly adjusts the high and low sequences for a message block, as well as cleaning up the deletion map accordingly (#7634)

### Filestore `syncBlocks` scheduling during snapshots fixed

- Affects: filestores using `syncBlocks`

When `syncBlocks` ran during a snapshot, it would not run again until the server was restarted.

> - Potential stream desyncs that could happen during stream snapshotting have been fixed (#7655)

### Retained-message permission check panic fixed

- Affects: MQTT retained-message permission checks (Inferred)

During a configuration reload that updates accounts or users, checking stored retained messages could panic if a user lacked the permissions needed to access them, including when no permissions were defined.

> - Fixed a panic that could occur when reloading config if the user did not have permission to access retained messages (#7596)

### MQTT JetStream API mapping through non-JetStream servers fixed

- Affects: MQTT accounts mapped from a non-JetStream leaf account to a JetStream-enabled hub account

On a leaf account that lacks JetStream but maps `JS.API.>` to `JS.HUB.API.>` on a JetStream-enabled hub, requests previously went out unmapped, so the MQTT client could not connect. They now traverse the server with the mapping applied, allowing the client to connect.

> - Fixed account mapping for JetStream API requests when traversing non-JetStream-enabled servers (#7598)

### QoS0 MQTT topics now follow account subject mappings

- Affects: QoS0 MQTT publishers and consumers using account imports/exports with subject mappings

Previously, a publish on `foo/x` from account A reached account B as `foo/x` instead of the mapped `bar/x`. Consumers now receive the topic corresponding to the mapped subject, such as `bar/x`.

> - QoS0 messages are now mapped correctly across account imports/exports with subject mappings (#7605)

### MQTT retained-message restoration now checks the message count

- Affects: MQTT retained-message restoration (Inferred)

After a restart, sequence gaps could make the restore-completion check time out even when all retained messages had been restored.

> - Loading retained messages no longer fails after restarting due to last sequence checks (#7616)

### Elastic pointers for file-based stream caches

- Affects: file-based streams

During garbage collection and memory pressure, the server can evict filestore caches early, returning memory to the operating system and helping avoid out-of-memory conditions. Depending on the number of assets and publish/access patterns, reported RSS may be lower or higher.

> -
> Elastic pointers in the filestore: File-based streams now use elastic pointers for its write-through caches. This allows the server to better respond during garbage collection, these caches can be evicted early to avoid out-of-memory conditions (see upgrade considerations below).
> -
> With the new elastic pointers in the filestore, it is expected that a NATS Server running 2.12 may show a different memory usage pattern to before. In some systems this may result in lower resident set size (RSS) reported, in others it may result in higher, depending on the number of assets and publish/access patterns.

https://docs.nats.io/release-notes/whats_new/whats_new_212

### Filestore caches freed on memory pressure

- Affects: NATS Server setups using filestore caches

Freeing caches on demand reduces the chance that sudden utilization spikes cause an out-of-memory kill. When resources allow, caches can be retained more optimistically to improve read access times.

> For the first time, the server will be able to respond to memory pressure by freeing filestore caches on demand and returning the memory to the operating system. This reduces the chance that sudden spikes in utilisation will result in an out-of-memory (OOM) kill. However, this means that the server can more optimistically retain caches in memory when available resources allow in order to facilitate improved read access times.

https://docs.nats.io/release-notes/whats_new/whats_new_212

## Enhancements (13)

- Configurable WebSocket ping interval (To use: A non-zero `ping_interval` in the `websocket` block)
- Atomic batch publishing for streams (To use: The stream configuration option `AllowAtomicPublish`)
- Increment/decrement counter semantics for streams (To use: The `AllowMsgCounter` stream configuration option)
- Stream message scheduling (To use: `AllowMsgSchedules` stream configuration option)
- Prioritized policy for pull consumers
- Adds the `server_metadata` map
- Mirroring streams can be promoted to primary
- Exponential backoff for cluster route and gateway reconnections (To use: Set `connect_backoff` to `true` for cluster routes or gateways.)
- System events from the global account
- `GOMAXPROCS` and `GOMEMLIMIT` added to NATS server stats
- Whole-subject `partition(n)` and `random(n)` subject-transform functions
- Leaf-node interest isolation with `isolate_leafnode_interest`
- Remote leaf node disabling through configuration reload (To use: Set `disabled: true` through a configuration reload)

## Dependency updates (8)

8 more, none mentioning security

- `- 1.25.5 (#7604)`
- `- github.com/google/go-tpm v0.9.7 (#7578)`
- `- github.com/nats-io/nkeys v0.4.12 (#7578)`
- `- golang.org/x/crypto v0.45.0 (#7578)`
- `- github.com/klauspost/compress v1.18.2 (#7604)`
- `- github.com/antithesishq/antithesis-sdk-go v0.5.0-default-no-op (#7604)`
- `- golang.org/x/crypto v0.46.0 (#7648)`
- `- golang.org/x/sys v0.39.0 (#7648)`

## Other changes (11)

- Faster sequence scans for subject-filtered sources
- JetStream metalayer stages and deduplicates recovery operations
- Faster JetStream consumer interest checks
- Clustered stream-creation data race fixed
- Filestore secure erase preserves correct subject tracking
- Stream health check replica reads protected by a read lock
- Filestore cache expiration after `errNoCache`
- Filestore indexes rebuilt and loading retried on sequence mismatch
- Streams and consumers using v2.12 features marked unsupported on downgrade
- Replicated streams flush data to disk asynchronously
- JetStream strict mode enabled by default

---

Summaries are produced by AI, so they can be wrong, and they are provided without warranty.
