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.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
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.
Related prompts
-
App Service & Functions Cold-Start and Failure Debug Prompt
Diagnose slow cold starts, 5xx errors, and startup failures on Azure App Service and Functions using app settings, logs, and platform behavior.
-
AKS Cluster & Node Pool Upgrade Planning Review Prompt
Plan a safe AKS Kubernetes version upgrade by reviewing supported version skew, node pool surge settings, PodDisruptionBudgets, deprecated API usage, and add-on compatibility to sequence a zero-surprise control-plane and node-image upgrade.
-
VM Scale Set Autoscale & Orchestration Review Prompt
Review an Azure Virtual Machine Scale Set for scaling correctness and resilience by analyzing autoscale rules, orchestration mode, upgrade policy, health probes, and zone balancing to stop flapping, slow scale-out, and unsafe instance replacement.
-
Azure Arc Hybrid Server Onboarding & Governance Review Prompt
Review an Azure Arc-enabled servers deployment for secure onboarding and consistent governance by analyzing Connected Machine agent health, identity and RBAC scope, policy/guest configuration assignments, and extension management across on-prem and multicloud machines.
More Azure with AI prompts & error guides
Browse every Azure with AI prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.