Client reconnect jitter limits during NATS server drain

What the Go client actually does

When a NATS server enters drain mode, it stops accepting new connections and keeps existing ones open until the configured drain_timeout expires. The Go client does not try to reconnect during that period; it simply waits for the server to close the connection. Once the server closes the socket, the client starts the normal reconnection loop.

Default back‑off and jitter values (Go client 2.x)

• ReconnectWait – the initial delay before the first retry (default 2 s).
• ReconnectWaitMax – the maximum delay after exponential back‑off (default 5 s).
• ReconnectJitterLimit – the random offset added to each retry (default 1 s).
• Jitter is uniformly distributed between 0 and ReconnectJitterLimit and is applied on top of the exponential back‑off value.

So the first retry will occur after roughly 2 s + [0‑1 s], the second after roughly 4 s + [0‑1 s], and so on, capped at 5 s + jitter.

Can you change it?

• Yes. The ReconnectJitterLimit option can be set to any time.Duration you choose, e.g. nats.ReconnectJitterLimit(2 * time.Second).
• To remove jitter entirely, set the limit to 0 or provide a custom ReconnectJitter function that returns 0.
• Keep in mind that a very small jitter limit can lead to a thundering herd when many clients reconnect at once after a drain. A common practice is to keep at least 200‑300 ms of jitter.

JetStream durable consumers and buffering during the reconnect window

• A durable consumer keeps its position in the stream even when the client is offline. While the client is disconnected, the server continues to accept new messages into the stream.
• Because the consumer is offline, those messages are not acknowledged and stay in the stream’s backlog. If the stream’s max_consumers or max_wait_time limits are hit, the server may start dropping or pausing new messages.
• When the client reconnects, it immediately resumes pulling from the backlog, which can cause a short burst of processing and temporary memory pressure on the client.
• To mitigate spikes, you can either increase the consumer’s max_wait_time, enable ack_wait tuning, or ensure your application can handle a burst of messages on reconnect.

Quick verification steps

1. Check the client’s options after connection:

   fmt.Printf("Jitter limit: %v\n", conn.Opts.ReconnectJitterLimit)
   

2. Run a test server with a short drain timeout:

   nats-server -DV --drain_timeout 5s
   

3. Observe reconnection timestamps in the client logs; you should see a pause of ~5 s followed by a retry after 2–3 s (plus jitter).
4. Enable JetStream debug logging (-js and -DV) to watch backlog growth during the disconnect.

What we need to pin down the exact timing for your upgrade

Could you share the NATS Go client version you are using and the drain timeout configured on the server? These details will confirm whether the defaults match the numbers above or if a newer release has adjusted them.