🐰 RabbitMQ Error: 'reject-publish' queue overflow returning basic.nack to publishers

Exact Error Message

With publisher confirms enabled, a queue configured with x-overflow: reject-publish returns a basic.nack once it is full:

2026-07-17 09:14:22.108 [warning] <0.1841.0> Queue 'events' in vhost '/' is full
 (max-length 50000), rejecting publish with basic.nack (overflow: reject-publish)

Client side (Java) the publisher sees the nack surfaced by the confirm listener:

com.rabbitmq.client.ConfirmListener.handleNack: delivery tag 41922, multiple=false
Broker rejected publish: queue 'events' at capacity (x-overflow=reject-publish)

If confirms are not enabled the message is simply discarded with no error, and you only notice via a growing gap between published and delivered counts.

What It Means

Every RabbitMQ queue can carry a length limit via x-max-length (message count) or x-max-length-bytes (total bytes). When that limit is reached, the x-overflow argument decides what happens to new messages. The default is drop-head, which silently discards the oldest ready message. Setting reject-publish instead tells the broker to refuse the new message.

Under reject-publish, a refused publish is reported to the publisher with basic.nack — but only if that channel is in publisher-confirm mode. A nack here means “the broker looked at your message and declined it because this queue is full,” not that the broker crashed or lost data. The related mode reject-publish-dlx additionally routes the rejected message to the queue’s configured dead-letter exchange.

Common Causes

• The queue hit x-max-length or x-max-length-bytes because consumers are slower than publishers.
• A policy set overflow to reject-publish intentionally, and a burst of traffic filled the queue.
• Consumers are down, disconnected, or stuck on unacked messages, so messages_ready never drains.
• The limit was set too low for normal peak load.
• A fan-out binds many queues and one slow queue starts nacking while others keep up.

Diagnostic Commands

Show current depth, the configured limit, and the overflow behavior for the queue:

rabbitmqctl list_queues name messages messages_ready messages_unacknowledged arguments --vhost /

Inspect the effective policy that set the overflow argument:

rabbitmqctl list_policies --vhost /
rabbitmq-diagnostics list_policies --vhost /

Check whether consumers are actually attached and draining:

rabbitmqctl list_queues name consumers messages_ready messages_unacknowledged --vhost /

Watch the broker log for reject/overflow warnings:

journalctl -u rabbitmq-server --since "10 min ago" | grep -iE 'overflow|reject|is full'

A queue with messages_ready pinned at the limit and consumers = 0 (or high messages_unacknowledged) is the classic signature: publishers keep arriving, nothing is being acknowledged, so every new publish is nacked.

Step-by-Step Resolution

1. Confirm this is a capacity nack, not a routing failure. A basic.nack under confirms with the queue at its x-max-length is overflow rejection. A basic.return is unroutable-message handling — a different problem.

2. Find the limit and current depth:

   rabbitmqctl list_queues name messages messages_ready arguments --vhost / | grep -i events

3. Fix the real bottleneck first — the consumers. If consumers = 0 or messages_unacknowledged is high, restart or scale consumers and raise prefetch so messages_ready drains below the limit.

4. If the limit is genuinely too low, raise it via policy (policies are the recommended way to manage limits, not per-queue x-arguments):

   rabbitmqctl set_policy events-limit "^events$" \
     '{"max-length":200000,"overflow":"reject-publish"}' \
     --apply-to queues --vhost /

5. Preserve rejected messages instead of losing them by switching to reject-publish-dlx and configuring a dead-letter exchange:

   rabbitmqctl set_policy events-limit "^events$" \
     '{"max-length":200000,"overflow":"reject-publish-dlx","dead-letter-exchange":"events.dlx"}' \
     --apply-to queues --vhost /

6. Make publishers handle the nack. Ensure publisher confirms are enabled and treat a nack as backpressure: slow down, retry with jitter, or shed load. Silently ignoring nacks turns a visible reject into invisible data loss.

7. Verify the queue drains and publishes are accepted again:

   rabbitmqctl list_queues name messages_ready consumers --vhost /

Prevention

• Choose the overflow mode deliberately: drop-head for lossy telemetry, reject-publish/reject-publish-dlx for work that must not be silently dropped.
• Always enable publisher confirms when using reject-publish; without them, rejected messages vanish with no signal.
• Alert on messages_ready approaching x-max-length before it saturates.
• Size limits to real peak load with headroom, and scale consumers to keep queues short.
• Route rejects to a DLX so overflow is recoverable rather than lost. See the prompt library for AI prompts that generate policy and consumer-scaling runbooks.

Related Errors

• NO_ROUTE (312) basic.return — an unroutable message, not a full queue.
• resource alarm / connection.blocked — a broker-wide memory or disk alarm blocks publishers instead of nacking one queue.
• publisher nack under mirroring/quorum — a nack because a quorum could not be reached, not because of length overflow.
• drop-head silent loss — the default overflow mode discards without any nack.

Frequently Asked Questions

Why do I get a nack instead of an error on publish? With reject-publish and publisher confirms on, a full queue is reported asynchronously via basic.nack, not as a synchronous exception on the publish call.

Where do rejected messages go? With reject-publish they are discarded; with reject-publish-dlx they are routed to the queue’s dead-letter exchange.

Does reject-publish work without publisher confirms? No — without confirms the broker still refuses the message, but the publisher receives no signal, so it looks like silent loss.

Is drop-head or reject-publish better? Use drop-head when the newest data matters most and old data is disposable; use reject-publish when you need backpressure and must not silently drop new work.

How do I change the overflow mode safely? Update the policy that matches the queue; policy changes apply without recreating the queue, unlike x-arguments set at declaration. For more, see the RabbitMQ guides.