1# Azure Service Bus SDK — Java
2 
3Package: `azure-messaging-servicebus` | [README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/servicebus/azure-messaging-servicebus/) | [Full Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/servicebus/azure-messaging-servicebus/TROUBLESHOOTING.md)
4 
5## Common Errors
6 
7| Exception | Cause | Fix |
8|-----------|-------|-----|
9| `AmqpException` (unauthorized-access) | Bad credentials or missing permissions | Verify connection string, SAS, or RBAC roles |
10| `AmqpException` (connection:forced) | Idle connection or transient network issue | Auto-recovers; no action needed |
11| `ServiceBusException` (MESSAGE_LOCK_LOST) | Lock expired during processing | Reduce processing time, disable auto-complete, settle manually |
12 
13## Key Issues
14 
15### Processor hangs with high prefetch + maxConcurrentCalls
16 
17`Update disposition request timed out.` — Client stops processing new messages.
18 
19**Cause**: Thread starvation when thread pool size ≤ `maxConcurrentCalls`.
20 
21**Fix**:
22```bash
23# Increase reactor thread pool
24-Dreactor.schedulers.defaultBoundedElasticSize=<value greater than concurrency>
25```
26Also set `prefetchCount(0)` to disable prefetch. This is more frequent in AKS environments.
27 
28### Implicit prefetch in ServiceBusReceiverClient
29 
30Even with prefetch disabled in the builder, `receiveMessages` API can re-enable prefetch implicitly. See [SyncReceiveAndPrefetch](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/servicebus/azure-messaging-servicebus/docs/SyncReceiveAndPrefetch.md).
31 
32### Autocomplete issues
33 
34Autocomplete and auto-lock-renewal have known issues with buffered/prefetched messages.
35 
36**Fix**: Use `disableAutoComplete()` and `.maxAutoLockRenewalDuration(Duration.ZERO)`, then settle messages explicitly.
37 
38## Enable Logging
39 
40Configure via SLF4J:
41```xml
42<logger name="com.azure.messaging.servicebus" level="DEBUG"/>
43```
44 
45See [Java SDK logging docs](https://learn.microsoft.com/azure/developer/java/sdk/troubleshooting-messaging-service-bus-overview) for details.
46 
47## Filing Issues
48 
49Include: namespace tier, entity type/config, machine specs, max heap (`-Xmx`), `maxConcurrentCalls`, `prefetchCount`, autoComplete setting, traffic pattern, and DEBUG-level logs (±10 min from issue).
50