Service Bus Dead-Letter Queues

A dead-letter queue (DLQ) is a sub-queue within a Service Bus queue or subscription that captures messages that cannot be delivered to any receiver or that the receiver explicitly rejects. The primary purpose is to isolate problematic messages from the main message flow, preventing them from blocking the processing of healthy messages. Without a DLQ, a single malformed message could cause infinite retries, exhaust the queue's storage, or degrade application performance. The DLQ acts as a safety valve and diagnostic tool.

When a message is sent to a Service Bus queue or topic subscription, it resides in the main queue until a consumer receives and completes it. If the message cannot be processed normally, it may be automatically moved to the DLQ. The move is atomic: the message is removed from the main queue and added to the DLQ in a single transaction. The DLQ is not a separate entity but a logical sub-queue accessible via a specific path: {queueName}/$DeadLetterQueue or {topicName}/Subscriptions/{subscriptionName}/$DeadLetterQueue. The DLQ stores the original message plus additional metadata: DeadLetterReason (a string explaining why) and DeadLetterErrorDescription (detailed error info). These properties are set by the system or by the sender when explicitly dead-lettering.

The Service Bus automatically moves a message to the DLQ under these conditions:

A consumer can explicitly move a message to the DLQ by calling DeadLetterAsync (or equivalent) on the message receiver. This allows the application to signal that a message is unprocessable (e.g., malformed JSON, invalid data). The consumer can provide a custom DeadLetterReason and DeadLetterErrorDescription. This is a common pattern when the consumer detects a business-level error that cannot be retried.

You can configure dead-lettering behavior at the queue or subscription level when creating the entity or updating its properties. Key properties:

Example using Azure CLI to create a queue with custom DLQ settings:

az servicebus queue create \
    --resource-group myRG \
    --namespace-name myNS \
    --name myQueue \
    --max-delivery-count 5 \
    --dead-lettering-on-message-expiration true

Example using C# to configure a queue:

var queueDescription = new QueueDescription("myQueue")
{
    MaxDeliveryCount = 5,
    DeadLetteringOnMessageExpiration = true
};
await namespaceManager.CreateQueueAsync(queueDescription);

To receive messages from the DLQ, you need to create a message receiver using the DLQ path. In C#:

var receiver = new MessageReceiver(
    connectionString,
    "myQueue/$DeadLetterQueue",
    ReceiveMode.PeekLock);

When you receive a message, you can inspect SystemProperties.DeadLetterReason and SystemProperties.DeadLetterErrorDescription. After processing (e.g., logging, fixing, resending), you must complete the message to remove it from the DLQ. If you cannot fix it, you might abandon it (which increments delivery count) or complete it to discard.

Azure Monitor provides metrics for DLQ: DeadletteredMessages (count of messages dead-lettered in a period). You can set alerts when the DLQ grows large. Also, you can view the DLQ message count in the Azure portal under the queue's metrics.

A large e-commerce platform uses Service Bus queues to process orders. Each order message contains JSON with customer details, items, and payment info. Occasionally, a message arrives with invalid JSON due to a bug in the web frontend. The order processing consumer attempts to parse the JSON, fails, and abandons the message. After 3 retries (configured maxDeliveryCount = 3), the message is dead-lettered. The operations team has a separate Azure Function that monitors the DLQ. When a message arrives, the function logs the DeadLetterErrorDescription (which includes the parsing exception) and sends an alert to the development team. The team can then inspect the original message, fix the bug, and resubmit the order manually via a custom portal. This pattern ensures that bad orders do not block the processing of good orders. In production, the queue handles 10,000 messages per minute, and the DLQ typically contains fewer than 10 messages per hour. If the DLQ grows large (e.g., >100), an alert triggers an automatic scaling of the DLQ processor. Misconfiguration: if maxDeliveryCount is set too high (e.g., 100), bad messages would retry many times, wasting processing resources and delaying other messages. Conversely, setting it too low (e.g., 1) might dead-letter transient failures that could succeed on retry.

An IoT solution collects telemetry from millions of devices into a Service Bus topic with multiple subscriptions. One subscription filters for temperature readings above 100°C using a SQL filter. Occasionally, a device sends a malformed message that causes the filter to throw an exception. With deadLetteringOnFilterEvaluationExceptions set to true (default), such messages are automatically moved to the subscription's DLQ. The IoT backend has a DLQ processor that analyzes these messages, identifies the faulty device, and sends a command to the device to reset its firmware. Without DLQ, the filter exception would cause the message to be silently dropped, and the device issue would go unnoticed. In this scenario, the DLQ acts as a diagnostic tool. Scale: the topic ingests 1 million messages per second across 10 partitions. The DLQ processor runs as a scaled-out set of VMs, each reading from the DLQ in batches of 100 messages. Performance consideration: reading from DLQ is slower than main queue because messages are stored in the same database but with additional indexing. Typically, DLQ processing is not latency-sensitive.

A bank uses Service Bus queues with sessions to process transactions in order. Each session represents a customer account. If a transaction message fails validation (e.g., insufficient funds), the consumer explicitly dead-letters the message with reason "InsufficientFunds" and description with account details. The DLQ is monitored by a reconciliation service that runs nightly. It reads all dead-lettered messages, correlates them with other data sources, and either fixes the transaction (e.g., by adjusting the amount) or flags it for manual review. This ensures that no transaction is lost and that the main queue remains free of problematic messages. The DLQ here is used as a business-level error queue, not just a system-level poison queue. Misconfiguration: if the consumer forgets to dead-letter and instead abandons, the message would retry indefinitely until max delivery count, causing unnecessary load. Explicit dead-lettering with a custom reason provides better semantics.