Should a RabbitMQ consumer nack-and-requeue or dead-letter a message when local processing times out?

The Decision Criteria

When a local processing timeout occurs, you should dead-letter the message (basic.nack or basic.reject with requeue=false) rather than requeuing it to the original queue.

The deciding factor is the risk of a "hot loop." Because a timeout is often deterministic—caused by a specific payload size, a complex calculation, or a consistently unresponsive downstream resource—requeuing the message immediately to the head of the queue can saturate your consumer's prefetch buffer. This prevents other valid messages from being processed and spikes CPU/IO without making progress.

Implementation Strategies

Bounding Retries via DLX (The Infrastructure Pattern)

Using the x-death header is the standard way to cap attempts without modifying the original message payload. The workflow is as follows:

1. Configure a DLX: Set the x-dead-letter-exchange argument on your primary queue.
2. Reject on Timeout: When the local deadline is hit, call basic.reject(requeue=false).
3. Retry Consumer: A separate consumer monitors the DLX queue. It inspects the x-death header (which contains a list of deaths, including the count).
4. Route or Park: If the count is below your threshold, the retry consumer republishes the message to the primary queue (optionally with a delay). If the threshold is exceeded, it moves the message to a permanent "parking lot" for manual inspection.

Application-Level Headers (The Deterministic Pattern)

If you require strict control or cannot use a DLX, maintain a custom header (e.g., x-retry-count). The consumer increments this value and republishes the message to the queue before acknowledging the original. This is more deterministic than x-death but increases broker load due to the explicit publish/ack cycle.

Verification and Edge Cases

Consumer Crash Mid-Processing

If a consumer is killed while processing a message (before it sends an ack, nack, or reject), RabbitMQ detects the connection loss. Because the message was never acknowledged, the broker automatically requeues it. This is a broker-level safety mechanism and is independent of your timeout policy.

Verification Steps

• DLX Routing: Publish a message, trigger a timeout, and verify the message appears in the DLX queue via the RabbitMQ Management UI.
• Header Inspection: Use a tool or consumer to inspect the x-death header to ensure the count increments correctly after each rejection.
• Crash Test: Start a long-running process, kill -9 the consumer process, and verify the message returns to the Ready state in the primary queue.

Diagnostic Note: Does your downstream dependency exhibit "cascading failure" (where retries make the outage worse)? If so, you must implement an exponential backoff in your retry consumer rather than immediate requeueing.