Azure Service Bus dead-letter queues: find, fix, resubmit

Every Azure Service Bus queue and subscription has a dead-letter queue (DLQ): a sub-queue where messages go when they cannot be delivered or processed. Nothing in the DLQ expires or retries by itself. Someone has to look at it.

Where the dead-letter queue lives

The DLQ is addressed as <queue>/$deadletterqueue for a queue, and <topic>/subscriptions/<subscription>/$deadletterqueue for a subscription. Its message count shows up in the entity's runtime properties.

Why messages get dead-lettered

• MaxDeliveryCountExceeded: the consumer abandoned or failed the message more times than the entity's max delivery count (10 by default).
• TTLExpiredException: the message expired while dead-lettering on expiration was enabled.
• Explicit dead-letter: your code called dead-letter with its own reason, usually for a message it can never process.
• Filter evaluation errors on subscriptions with dead-lettering on filter exceptions enabled.

The reason and description are stored in the DeadLetterReason and DeadLetterErrorDescription properties. Read those first.

How to fix and resubmit

1. Fix the cause: deploy the consumer fix, or correct the bad data at the source.
2. Peek the DLQ and group messages by reason so you know what you are resubmitting.
3. Resubmit by sending a copy back to the original entity, then complete the dead-lettered original.
4. Watch the main queue to confirm the messages are now processed.

Resubmitting before the fix is live only sends the messages back to the DLQ.

Resubmitting from the Azure portal

The portal's Service Bus Explorer can re-send a dead-lettered message, but it sends a copy and leaves the original in the DLQ, so you have to complete it separately.

Resubmitting from a subscription

Service Bus cannot send to a single subscription. Whatever tool you use, a message resubmitted from a subscription's DLQ goes back to the topic and reaches every subscription whose filter matches, not only the one that failed. Make sure the other consumers are idempotent before you resubmit. How Fumiq compares to the portal.

Doing it in Fumiq

Fumiq shows the dead-letter count next to every queue and subscription. Open the Dead Letter tab to filter by reason or body content, edit a message if its payload was the problem, and resubmit one message or a whole selection. Fumiq sends the copy and completes the original for you.

Download Fumiq and try every feature free for 30 days, no credit card required.