To replay dead-lettered RabbitMQ messages, consume them from the dead-letter queue (DLQ) and republish them to the intended exchange or queue. Use RabbitMQ Shovel for a configurable transfer, or a purpose-built consumer when you need filtering or application-specific handling. Configure the transfer so the source message is acknowledged only after the destination confirms publication; this reduces handoff loss, but does not guarantee exactly-once processing.
What replay does—and what it does not do
A dead-letter exchange (DLX) is a normal RabbitMQ exchange. When a message is dead-lettered, RabbitMQ publishes it to the configured DLX; bindings and the routing key determine which queue receives it. If the source queue has no dead-letter routing key configured, RabbitMQ uses the message’s original routing keys. Replay is a separate operation: it transfers a message already in the DLQ back into the topology where it should be processed.
Messages can be dead-lettered after a consumer rejects or negatively acknowledges them with requeue=false, a message TTL expires, a queue reaches its length limit, or a quorum queue’s delivery limit is exceeded. The expiry of an entire queue does not, by itself, dead-letter all its messages. See RabbitMQ’s Dead Letter Exchanges documentation for the conditions and routing behavior.
RabbitMQ’s DLX guidance does not describe a dedicated built-in replay command. A practical replay uses a message transfer mechanism—such as Shovel or a consumer that republishes messages—to send messages from the DLQ to their intended destination.
#1 Best Overall
Prepare the replay
- Fix the cause first. Confirm the consumer, dependency, or message-handling problem that caused dead-lettering is resolved. Otherwise, the replayed messages may fail and dead-letter again.
- Identify the exact source and destination. Confirm the virtual host and DLQ, the original source application, the intended exchange or queue, its bindings, and the routing key. Decide whether to replay the whole queue or only a selected subset.
- Inspect representative messages. Check the dead-letter history, reason, first and most recent queue and exchange, original routing keys, content type, correlation identifiers, and any application-specific idempotency key. For AMQP 0-9-1, RabbitMQ records dead-letter history in
x-death; for AMQP 1.0, it usesx-opt-deaths. The RabbitMQ dead-letter documentation describes this metadata. A dead-letter cycle can cause RabbitMQ to drop a message if it cycles without a rejection. - Choose a transfer method. Use Shovel for a configurable queue-to-destination message pump when its routing and property behavior meet your needs. Use a purpose-built consumer if you need to filter, transform, throttle, or make per-message business decisions.
- Test routing with a small batch. Check that messages arrive in the intended target queue and that the application handles them correctly before replaying at scale. A wrong routing key or binding can route messages elsewhere or leave them unrouted.
- Run with confirmation-aware handoff. Arrange for the source message to be acknowledged only after publication to the destination is confirmed. Make processing idempotent or deduplicate by a stable business identifier, because failures and retries can still produce duplicates.
- Monitor and stop if needed. Watch source and target queue depth, transfer rate, consumer errors, and new dead-letter growth. Pause or stop the transfer if routing or processing is incorrect. RabbitMQ Management displays queue lengths and rates; see its Management documentation.
Choose a replay method
| Method | Best for | Trade-offs |
|---|---|---|
| RabbitMQ Shovel | Configurable queue-to-destination transfers, including transfers within or between clusters. | RabbitMQ describes Shovel as a minimalistic message pump. Its transfer can wait for destination publication or confirmation before acknowledging the source. It is unidirectional, so check the source, destination, and routing configuration carefully. See the Shovel Plugin documentation and Configuring Dynamic Shovels. |
| Purpose-built consumer | Selective replay, rate limiting, message transformation, business checks, or application-specific handling. | You own the implementation and operations. Use manual source acknowledgements, publisher confirms, suitable retries, and idempotent processing. The exact implementation depends on your client and policies; RabbitMQ documents the underlying consume-and-republish transfer pattern in its Shovel documentation. |
| Management HTTP API | A small administrative action where a messaging client or Shovel is not practical. | RabbitMQ supports publishing and consuming through the HTTP API, but recommends binary messaging protocols for normal message transfer because HTTP messaging is less efficient and lacks protocol features such as confirmations. See the Management documentation. |
Configure routing and acknowledgements safely
RabbitMQ lets you configure a queue’s DLX through a policy or queue arguments. Policies are generally easier to change without redeploying applications; if both a policy and queue arguments specify the setting, the queue arguments take precedence. Review the source queue’s effective DLX and routing-key configuration before replaying, and verify that the replay destination does not send messages straight back into the same dead-letter route.
For a custom consumer, use manual acknowledgements and publisher confirms: publish the message to the chosen destination, wait for confirmation, then acknowledge the message on the DLQ. If publication fails or its outcome is uncertain, do not acknowledge the source as though delivery succeeded; retry or handle the uncertainty deliberately. Confirmation-aware transfer reduces the chance of losing a message between source and destination, but a retry after an uncertain outcome can duplicate it. Use application-level idempotency rather than assuming exactly-once processing.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Understand quorum queue dead-lettering
At-least-once dead-lettering is a quorum queue feature, not a guarantee for every RabbitMQ queue type. It requires dead-letter-strategy=at-least-once, overflow=reject-publish, and a configured DLX. With this strategy, the source retains dead-lettered messages until target queues confirm receipt. That provides a stronger handoff, but uses additional resources; unavailable or rejecting destinations can delay movement, and forwarding retries can result in duplicates. Details and constraints are in the Quorum Queues documentation.
Check the broker version and queue type when diagnosing why messages hit a delivery limit. RabbitMQ 4.0 and later set the default quorum queue delivery limit to 20. Once a message exceeds that limit, it is dropped or dead-lettered depending on whether a DLX is configured; this is a product default, not a universal limit for all queue types or broker versions. See the Quorum Queues documentation.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
