🐰 RabbitMQ Error: x-max-length Reached, Messages Dropped or Dead-Lettered

Exact Error Message

When a queue hits its x-max-length limit with the default drop-head overflow, older messages are evicted. With a DLX attached, the log records the eviction reason as maxlen:

[info] <0.1201.0> Message dead-lettered from queue 'events' with reason 'maxlen'
[info] <0.1201.0>   (queue length limit x-max-length=10000 exceeded).

If the queue uses x-overflow: reject-publish, publishers instead receive a basic.nack:

[warning] <0.1330.0> Queue 'events' has reached its max length (10000);
[warning] <0.1330.0>   rejecting publish (x-overflow=reject-publish).

What It Means

A queue can be capped by message count (x-max-length) or total body size (x-max-length-bytes). When the cap is reached, RabbitMQ applies the queue’s overflow behaviour:

• drop-head (default): the oldest ready message is discarded to make room. If a DLX is set, that message is dead-lettered with reason maxlen.
• reject-publish: the broker refuses the new publish and returns basic.nack to the publisher (a confirming publisher sees the nack; a non-confirming publisher loses the message silently).

Either way, data is being shed because the queue is filling faster than it drains.

Common Causes

• Consumers are slower than publishers, so the queue rides at its length cap continuously.
• A deliberately low x-max-length set to bound memory, now too small for the traffic.
• x-max-length-bytes reached because message bodies are larger than sized for.
• drop-head chosen where the workload actually needs reject-publish back-pressure.
• Consumers offline during a burst, so the cap evicts a backlog of unprocessed messages.

Diagnostic Commands

Show the length limits and overflow behaviour on the queue:

rabbitmqctl list_queues name arguments policy messages --formatter=pretty_table

Compare publish and deliver rates to confirm the queue is drain-limited:

rabbitmq-diagnostics list_queues name messages message_stats.publish_details.rate message_stats.deliver_get_details.rate

Check the effective policy that may be applying the limit:

rabbitmqctl list_policies -p /

Confirm evictions are happening by tailing for reason maxlen:

rabbitmq-diagnostics log_tail --number 100

Step-by-Step Resolution

1. Read the queue’s limit and overflow mode:

rabbitmqctl list_queues name arguments messages -p /

2. Decide whether you want back-pressure or eviction. To stop silently dropping the oldest messages, switch to reject-publish via policy so publishers are told to slow down:

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

3. Make sure publishers use publisher confirms so a basic.nack is handled instead of lost. Without confirms, reject-publish drops the message just as quietly as drop-head.

4. If eviction is acceptable but you need an audit trail, attach a DLX so maxlen evictions are captured rather than discarded:

rabbitmqctl set_policy -p / events-dlx "^events$" \
  '{"max-length": 10000, "dead-letter-exchange": "dlx.events"}' --apply-to queues

5. Address the real cause: scale consumers or raise prefetch so the queue drains. Confirm the backlog is clearing:

watch -n 2 'rabbitmqctl list_queues name messages messages_ready'

6. If the limit itself is too low for legitimate traffic, raise it deliberately and monitor memory:

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

Prevention

• Choose overflow mode intentionally: reject-publish for back-pressure, drop-head only when losing the oldest data is acceptable.
• Always pair reject-publish with publisher confirms so nacks are observed.
• Attach a dead-letter exchange to any length-capped queue so evictions are auditable.
• Alert on queue depth approaching x-max-length rather than after messages are already dropped.
• Right-size consumer count and prefetch so steady-state depth stays well under the cap.

Related Errors

• Message dead-lettered ... reason 'expired' — dropped by TTL, not length limit.
• PRECONDITION_FAILED - inequivalent arg 'x-max-length' — redeclaring a queue with a different limit.
• connection.blocked / basic.nack from a memory alarm — a broker-wide resource alarm, not a per-queue cap.
• NO_ROUTE on the DLX — evicted messages dropped again because the dead-letter exchange has no binding.

Frequently Asked Questions

Why is my queue dropping the oldest messages? The queue reached x-max-length (or x-max-length-bytes) with the default drop-head overflow, which evicts the oldest ready message to admit a new one.

How do I make RabbitMQ reject new publishes instead of dropping old ones? Set overflow: reject-publish via policy and enable publisher confirms so publishers receive and handle the basic.nack. A back-pressure tuning prompt is in the RabbitMQ prompt library.

Does reject-publish guarantee no message loss? Only if the publisher uses confirms and handles the nack. Without confirms, a rejected publish is lost as silently as a drop-head eviction.

Can I see which messages were dropped? Attach a dead-letter exchange so maxlen evictions are re-routed and inspectable rather than discarded. For more messaging fixes, see the RabbitMQ guides.