Configure Azure Service Bus MaxDeliveryCount and inspect the dead-letter sub-queue for a queue or subscription
domain: learn.microsoft.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Set the MaxDeliveryCount property on the queue or subscription (default is 10; valid range is 1 to 2147483647) at creation or via an update operation
Understand that each time a peek-locked message is explicitly abandoned or its lock expires without completion, the message's delivery count increments
Once delivery count exceeds MaxDeliveryCount, Service Bus automatically moves the message to the entity's dead-letter sub-queue with a dead-letter reason of MaxDeliveryCountExceeded
Access the dead-letter sub-queue directly using the path syntax <queue-path>/$deadletterqueue for queues, or <topic-path>/Subscriptions/<subscription-name>/$deadletterqueue for subscriptions
Inspect dead-lettered messages using a client/tool such as Service Bus Explorer, the Azure CLI, or an SDK receiver pointed at the DLQ sub-queue path, and read the DeadLetterReason/DeadLetterErrorDescription properties
Build a reprocessing or alerting pipeline that periodically drains and inspects the DLQ rather than letting it grow unbounded
Known gotchas
This automatic dead-lettering behavior cannot be disabled — if you want messages to essentially never be dead-lettered on delivery-count grounds, you must set MaxDeliveryCount to a very large number rather than turning the feature off
The dead-letter sub-queue is implicit — it doesn't need to be created and cannot be deleted or managed as an independent entity separate from its parent queue/subscription
Messages can also be dead-lettered explicitly by application code (DeadLetter()) or due to other conditions like TTL expiry or auto-forwarding hop limits, not only MaxDeliveryCountExceeded — check the DeadLetterReason to distinguish causes
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?