NATS JetStream Stream ↔ Consumer: Stale Message Retrieval with max_age Retention

NATS JetStream Stream ↔ Consumer: Stale Message Retrieval

When a JetStream stream is configured with a max_age retention policy, messages older than the specified duration become eligible for removal. However, JetStream does not purge them instantly; removal occurs during periodic housekeeping cycles performed by the stream leader. The default housekeeping interval is roughly 30 seconds in recent NATS releases, and this value can be tuned via server configuration. In a clustered environment, replicas may lag behind the leader’s housekeeping, further extending the window during which expired messages remain accessible.

This nondeterministic delay raises questions for applications that rely on consumer queries or cached results to reflect the true state of the stream. The uncertainty lies in whether a consumer might still receive a message that has technically exceeded its max_age but has not yet been purged by housekeeping.

Key questions for investigation:

• In a clustered deployment, how does the leader‑driven housekeeping affect message visibility for consumers connected to replicas?
• What is the effective purge window between a message exceeding its max_age and its removal from the stream, and can this window be reliably configured?
• Can consumers rely on JetStream APIs to guarantee that a message returned after max_age has already been purged, or must they implement additional checks?