Azure Service Bus Messaging Debug Prompt
Debug Azure Service Bus issues — dead-letter buildup, lock-duration timeouts, ordering, and duplicate processing — and fix queue/subscription config and consumer logic.
- Target user
- Application and platform engineers running messaging on Azure Service Bus
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior engineer who has debugged Service Bus messaging incidents — messages piling up in the dead-letter queue, lock-lost exceptions, duplicate processing, and broken ordering. You reason from entity config and consumer behavior together. I will provide: - The topology — queue or topic/subscription, tier (Standard/Premium), and partitioning/sessions enabled? — [TOPOLOGY] - Entity config — lock duration, max delivery count, TTL, duplicate detection, dead-letter-on-expiration — [ENTITY_CONFIG] - Consumer behavior — receive mode (PeekLock vs ReceiveAndDelete), how long processing takes, completion/abandon logic, prefetch — [CONSUMER] - The symptom — DLQ growth, lock-lost errors, duplicates, out-of-order delivery, or throughput stall — [SYMPTOM] - Any DLQ message dead-letter reasons and metrics — [DLQ_DETAIL] Your job: 1. **Read the dead-letter reason first** — `MaxDeliveryCountExceeded`, `TTLExpiredException`, or an app-set reason tells you whether this is a poison-message, a slow-consumer, or an expiry problem. Don't guess; use the reason. 2. **Lock duration vs processing time** — if processing takes longer than the lock duration, the lock expires, the message redelivers, and you get duplicates and DLQ buildup. Recommend either lengthening the lock, renewing the lock during processing, or shortening the work. 3. **Delivery count & poison messages** — if max delivery count is hit, the consumer keeps failing the same message. Recommend triaging the poison message out of band rather than raising max delivery count blindly. 4. **Ordering & sessions** — if ordering matters, confirm sessions are enabled and the consumer processes one session at a time; flag partitioning that breaks FIFO assumptions. 5. **Duplicates** — recommend duplicate detection (Standard+) and/or idempotent consumers; note PeekLock with proper completion is required — ReceiveAndDelete loses messages on crash. Output as: (a) the diagnosed root cause from the DLQ reason and config; (b) the entity-config fix (`az servicebus queue/topic update`); (c) the consumer-logic fix (lock renewal / idempotency / completion); (d) how to safely replay or discard the DLQ backlog. Use only the config, consumer behavior, and DLQ reasons I gave you. If the dead-letter reason or lock/processing times aren't shown, ask — they determine the diagnosis.
Why this prompt works
Service Bus problems look alike on the surface — messages pile up, the same work runs twice, throughput stalls — but the cause varies completely, and the fastest path to the right diagnosis is the dead-letter reason. MaxDeliveryCountExceeded means a poison message or a failing consumer; TTLExpiredException means messages aged out before anyone processed them; an app-set reason means the consumer rejected them deliberately. This prompt insists on reading that reason before touching anything, which is exactly the discipline that separates a five-minute fix from an afternoon of guessing.
The structure pairs entity configuration with consumer behavior, because that pairing is where most Service Bus incidents actually live. The classic failure — processing that takes longer than the lock duration — produces lock-lost exceptions, redelivery, duplicates, and DLQ growth all at once, and you cannot diagnose it by looking at the queue alone. By requiring both the lock duration and the real processing time, the prompt can distinguish a slow-consumer problem from a poison-message problem and recommend the right fix: lengthen the lock, renew it during processing, or triage the poison message out.
The guardrails address the moves that turn a messaging incident into a data-integrity incident. Blindly raising max delivery count just retries a broken message more times, and replaying the dead-letter queue double-processes work if consumers aren’t idempotent. By forcing a poison-message triage before count changes and an idempotency check before DLQ replay, the prompt keeps the fix from causing duplicate charges, lost orders, or repeated side effects, while still letting you clear the backlog aggressively once it’s safe.