Key Value with TTL

[alberk8]

I have setup Nats server v2.11.8 with jetstream. The bucket with TTL of 1m and Limit Market TTL of 5m then i created a kv with ttl of 2. What I am getting from the KV watcher is that the KV is expiring in 1m. Is this the correct behavior?

nats kv create user_sessions user1 "data" --ttl=2m

KV watcher

[2025-09-06 10:02:25] PUT user_sessions > user1: data
[2025-09-06 10:03:25] PURGE user_sessions > user1

Information for Key-Value Store Bucket user_sessions created 2025-09-06 09:47:05

Configuration:

            Bucket Name: user_sessions
           History Kept: 1
          Values Stored: 0
             Compressed: false
  Per-Key TTL Supported: true
       Limit Marker TTL: 5m0s
     Backing Store Kind: JetStream
            Bucket Size: 0 B
    Maximum Bucket Size: unlimited
     Maximum Value Size: unlimited
            Maximum Age: 1m0s
       JetStream Stream: KV_user_sessions
                Storage: File

[MauriceVanVeen]

This is expected based on the MaxAge of 1m, which removes any message after that TTL. If you'd instead use 10m for the MaxAge, then the message and delete marker don't get removed earlier.

[alberk8]

What is the purpose of the Limit Marker TTL time?, is the the time for the TTL purge message to stay around after the purge?

[MauriceVanVeen]

Correct, when a message is removed due to MaxAge or per-message TTL, the limit marker TTL is how long the created delete marker will stay.

[alberk8]

Thanks, I wish the documentation is more clear on this. Even AI is confused, Gork and DeepSeek got it wrong only ChatGPT got it right.

[alberk8]

The most confusing part is that MaxAge takes precedence over the per-message KV TTL. This can be a real headache to troubleshoot if you’re not fully aware of how it works.

[MauriceVanVeen]

The docs are a bit light on the TTL-side, but MaxAge should be in there. If you're willing, could contribute a PR to improve the docs here: https://github.com/nats-io/nats.docs