NATS 2.11 Consumer Pausing

The NATS 2.11 release introduced a powerful new feature that many NATS users have been waiting for: the ability to pause and resume stream consumers. In this article, we’ll explore how consumer pausing works, when to use it, and how to configure it using the NATS CLI.

What is Consumer Pausing?

Consumer pausing allows you to temporarily stop a consumer from processing messages from a stream without the need to delete a consumer. This is particularly useful for maintainance work or during deployments. It can be also useful for urgent bugfixes when the consumer accidentally acks messages due to a bug.

How Consumer Pausing Works

When you pause a consumer, the consumer immediately stops delivering messages to cosumer clients. All configuration remains intact when pausing a cosumer.

One thing to keep in mind: If you have a pull consumer and you pull a large number of messages in one batch, the consumer client won’t stop consuming messages from that batch. It will only stop after the entire batch has been consumed and it attempts to pull the next batch from the NATS server.

When pausing a consumer, you always have to specify a duration or exact time when the consumer will automatically resume. So that defined time needs to be monitored during maintence windows and eventually extended when the maintainance takes longer than expected.

Let’s dive into how to use this feature with the NATS CLI.

Pausing Consumers with the NATS CLI

The nats consumer pause command allows you to temporarily suspend a consumer. Here’s the basic syntax:

nats consumer pause [<flags>] [<stream>] [<consumer>] [<until>]
Command Arguments

<stream>: The name of the stream containing the consumer
<consumer>: The name of the consumer to pause
<until>: (Optional) The time until which the consumer should remain paused

Command Flags

-f, --force: Force pause without confirmation prompts

Example: Pausing a Consumer

Let’s say we want to pause a consumer named discord_notifier on the orders stream for 10 minutes:

nats consumer pause orders discord_notifier

When running this command, you’ll be prompted to specify how long you want to pause the consumer:

[demo] ? Pause until (time or duration) 10m
[demo] ? Really pause Consumer orders > discord_notifier until 2025-05-15 19:54:27 Yes
Paused orders > discord_notifier until 2025-05-15 19:54:27 (9m58s)
Specifying Pause Duration
You can specify the pause duration in several formats:

Duration format: 10m (minutes), 2h (hours), 30s (seconds), 1d (days)
Absolute time: 2025-05-15 20:30:00

If you don’t specify a duration when running the command, you’ll be prompted to enter one.

Checking the Status of a Paused Consumer

To verify that a consumer is paused and check when it will automatically resume, use the nats consumer info command:

nats consumer info orders discord_notifier

The output will include a Pause Until Deadline in the Configuration section and a Paused Until field in the State section, both showing the time when the consumer will automatically resume:

Information for Consumer orders > discord_notifier created 2025-05-14T09:25:05+02:00
Configuration:
Name: discord_notifier
Pull Mode: true
Filter Subject: calculate_summaries
Deliver Policy: All
Ack Policy: Explicit
Ack Wait: 300µs
Replay Policy: Original
Max Ack Pending: 1,000
Max Waiting Pulls: 512
Paused Until Deadline: 2025-05-15 19:54:27 (9m26s remaining)
State:
Host Version: 2.11.3
Required API Level: 1 hosted at level 1
Last Delivered Message: Consumer sequence: 0 Stream sequence: 0
Acknowledgment Floor: Consumer sequence: 0 Stream sequence: 0
Outstanding Acks: 0 out of maximum 1,000
Redelivered Messages: 0
Unprocessed Messages: 0
Waiting Pulls: 0 of maximum 512
Paused Until: 2025-05-15 19:54:27 (9m26s remaining)

Resuming Consumers

If you need to resume a consumer before its automatic resume time, you can use the nats consumer resume command:

nats consumer resume [<flags>] [<stream>] [<consumer>]
Command Arguments

<stream>: The name of the stream containing the consumer
<consumer>: The name of the consumer to resume

Command Flags

-f, --force: Force resume without confirmation prompts

Example: Resuming a Consumer

To resume our paused consumer before its automatic resume time:

nats consumer resume orders discord_notifier

You’ll be prompted to confirm:

[demo] ? Really resume Consumer orders > discord_notifier Yes
Resumed orders > discord_notifier

Tips for Effective Consumer Pausing

• Set reasonable durations: Choose pause durations that make sense for your use case and extend the time when the maintenance takes longer.
• Monitor paused consumers: Regularly check which consumers are paused to avoid forgetting about them.
• Wait for pull cosumers before starting the maintenance: When you use pull consumers, be aware that the consuming of message won’t stop right away when the consumer clients pull messages in batches. Make sure the pulled batches are consumed before starting with the maintenance.
• Automate pausing: Consider automating consumer pausing as part of your maintenance scripts.
• Consider message backlog: Be aware that messages will accumulate while consumers are paused.

Conclusion

The consumer pausing feature in NATS 2.11 adds an important operational tool to the JetStream ecosystem. By allowing temporary suspension of message processing without losing consumer state, it enables more flexible management of your messaging systems.

Whether you’re performing maintenance or debugging issues, consumer pausing gives you a clean way to temporarily halt message processing and resume it exactly where you left off.