🚨 RabbitMQ Error Guide: 'consumer_timeout' Delivery Acknowledgement Timed Out

Exact Error Message

The broker closes the channel because an outstanding delivery was not acknowledged within consumer_timeout:

operation none caused a channel exception precondition_failed:
delivery acknowledgement on channel 1 timed out. Timeout value used: 1800000 ms.
This timeout value can be configured, see consumers doc guide to learn more

In the broker log:

Consumer amq.ctag-9Kds... on channel 1 and queue 'reports.generate' in vhost '/'
 has timed out waiting for a delivery acknowledgement. Timeout used: 1800000 ms.
Closing channel.

Client side it appears as a channel-level PRECONDITION_FAILED (406) shutdown, after which the unacked message is requeued and redelivered.

What the Error Means

When a consumer uses manual acknowledgement (no_ack=false), RabbitMQ expects an basic.ack, basic.nack, or basic.reject for each delivered message within consumer_timeout — 30 minutes (1,800,000 ms) by default in modern RabbitMQ. If the consumer holds a delivery longer than that without acking, the broker assumes the consumer is stuck, closes the channel, and requeues the unacked message so another consumer can take it.

This protects the broker from a consumer that has hung: an un-acked message would otherwise stay in memory indefinitely. The timeout measures wall-clock time from delivery to ack, not processing time alone — anything that delays the ack (slow work, blocking I/O, a stuck thread, or simply too many prefetched messages processed serially) can trip it.

The subtle trap is prefetch. If basic.qos(prefetch_count=N) lets the broker push N messages to a consumer that processes them one at a time, the timer for every one of those N deliveries starts when it is sent, not when the consumer gets around to it. So even if each message takes 30 seconds, a prefetch of 100 means the hundredth message has been waiting ~50 minutes by the time it is processed — well past the 30-minute default — and the broker closes the channel mid-batch. Lowering prefetch is therefore often the real fix, even though the symptom looks like “processing is too slow.”

Common Causes

• Genuinely long processing. A task (report generation, video transcode, large batch) takes longer than 30 minutes to finish before acking.
• High prefetch with serial processing. A large basic.qos prefetch delivers many messages at once; the last ones wait in the buffer past the timeout while earlier ones are processed one at a time.
• A blocked or deadlocked consumer thread. The consumer fetched a message and then blocked on a lock, an external API, or a database that never responds.
• Forgotten or conditional ack. A code path returns without acking (exception swallowed, early return), so the message is never acknowledged.
• Acking on the wrong/closed channel. The consumer processes on a different thread/channel and the ack never reaches the delivering channel.
• Long GC pauses or an overloaded consumer host. The process is alive but starved, delaying acks past the limit.

How to Reproduce the Error

Lower the timeout to make it fast, then sleep longer than the limit before acking:

# broker config (rabbitmq.conf): consumer_timeout = 15000   # 15s
basic.qos(prefetch_count=1)
basic.consume(queue='reports.generate', no_ack=false)
on_message(msg):
    sleep(30s)        # longer than consumer_timeout
    basic.ack(msg)    # broker has already closed the channel here

After 15 seconds the broker logs the timeout, closes channel 1, and requeues the message. The eventual basic.ack fails because its channel is gone.

Diagnostic Commands

# Current consumer_timeout value in effect
rabbitmqctl environment | grep -A1 consumer_timeout

# Or via diagnostics
rabbitmq-diagnostics environment | grep -i consumer_timeout

# Queues with many unacked messages (long-held deliveries)
rabbitmqctl list_queues name messages_unacknowledged consumers \
  --sort=messages_unacknowledged | tail -10

# Per-consumer prefetch and ack mode — high prefetch + serial work is the classic trap
rabbitmqctl list_consumers queue_name consumer_tag prefetch_count ack_required | head -20

# Redeliver rate hint: messages requeued after timeout show as redelivered
rabbitmqctl list_queues name messages_ready messages_unacknowledged | grep -i reports

# Find timeout events in the broker log
journalctl -u rabbitmq-server --since "1 hour ago" | grep -i 'acknowledgement.*timed out'

# Channel churn from repeated closures
rabbitmqctl list_channels pid number messages_unacknowledged | head -20

A high prefetch_count combined with high messages_unacknowledged on a queue whose consumers do slow work is the fingerprint of a timeout caused by buffering rather than a single slow message.

Step-by-Step Resolution

1. Confirm it is a consumer ack timeout. The log line delivery acknowledgement ... timed out and a precondition_failed channel close confirm it. Note the timeout value reported.

2. Lower prefetch first. If processing is slow, set basic.qos(prefetch_count=1) (or a small value). With high prefetch, the broker counts wall-clock time on buffered messages too, so the last message in a batch can time out even though each item is quick.

3. Make work shorter or asynchronous. For genuinely long tasks, ack early and track completion out-of-band, or break the work into smaller messages. Acking before the long-running step (with idempotent processing) avoids holding the delivery.

4. Raise consumer_timeout only if the work is legitimately long. Set it in rabbitmq.conf (e.g., consumer_timeout = 3600000 for one hour). This is a broker-wide setting and requires a node restart or rabbitmqctl eval to apply; prefer fixing prefetch/processing first.

5. Fix swallowed exceptions and missing acks. Ensure every code path acks, nacks, or rejects. Wrap processing so failures basic.nack (with requeue policy) rather than leaving the delivery dangling.

6. Ack on the delivering channel. Acks are channel-scoped. Do not ack from a different channel or after the channel has been recreated by a reconnect.

7. Verify. Reprocess and confirm the channel stays open, messages_unacknowledged drains, and the timeout log line stops appearing.

Prevention and Best Practices

• Keep prefetch_count small for slow consumers so buffered messages do not age out.
• Design consumers to ack promptly; offload long work or chunk it into smaller messages.
• Make processing idempotent so requeue-after-timeout redeliveries are safe.
• Only raise consumer_timeout deliberately and document why; the 30-minute default catches real hangs.
• Always ack/nack in a finally so no exception path leaves a delivery unacked.
• Alert on messages_unacknowledged and on repeated acknowledgement timed out log lines.

Related Errors

• consumer cancelled notification: the broker ends a subscription due to queue deletion or node failure, a different cause than ack timeout.
• publisher nack received: the publish-side confirm failure, unrelated to consumer acks.
• missed heartbeats / timeout: a connection-level timeout, distinct from the delivery-ack timeout described here.
• resource alarm: large unacked backlogs pin memory and can trip a memory alarm alongside ack timeouts.

Frequently Asked Questions

What is the default consumer_timeout? 30 minutes (1,800,000 ms) in modern RabbitMQ. Earlier versions had a 15-minute default or none at all.

Does the timeout measure processing time or wall-clock time? Wall-clock time from delivery to ack. With high prefetch, messages sitting in the consumer’s buffer count down too, so the last message in a batch can time out even if processing is fast.

What happens to the unacked message? It is requeued and redelivered (flagged redelivered) so another consumer can process it. Make processing idempotent to handle this safely.

Should I just increase consumer_timeout? Only if the work is genuinely long. First reduce prefetch and shorten or offload processing; raising the timeout hides hangs that the default is meant to catch.

Is consumer_timeout per-consumer or broker-wide? It is a broker-wide (node) setting in rabbitmq.conf. It applies to all manual-ack consumers on that node.