1# Azure Event Hubs SDK — Java
2 
3Package: `azure-messaging-eventhubs` | [README](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs/) | [Full Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs/TROUBLESHOOTING.md)
4 
5> ⚠️ **Note:** The detailed Java troubleshooting guide has moved to [Microsoft Learn](https://learn.microsoft.com/azure/developer/java/sdk/troubleshooting-messaging-event-hubs-overview).
6 
7## Common Errors
8 
9| Exception | Cause | Fix |
10|-----------|-------|-----|
11| `AmqpException` (connection:forced) | Idle connection disconnected | Auto-recovers; no action needed |
12| `AmqpException` (unauthorized-access) | Bad credentials or missing permissions | Verify connection string, SAS, or RBAC roles |
13| `AmqpException` (resource-limit-exceeded) | Too many concurrent receivers | Reduce receiver count or upgrade tier |
14| `OperationTimeoutException` | Network issue or throttling | Check firewall, try AMQP over WebSockets (port 443) |
15 
16## Enable Logging
17 
18Configure via SLF4J. Add `logback-classic` dependency and set level for `com.azure.messaging.eventhubs`:
19 
20```xml
21<logger name="com.azure.messaging.eventhubs" level="DEBUG"/>
22```
23 
24For AMQP frame tracing:
25```xml
26<logger name="com.azure.core.amqp" level="DEBUG"/>
27```
28 
29See [Java SDK logging docs](https://learn.microsoft.com/azure/developer/java/sdk/troubleshooting-messaging-event-hubs-overview) for details.
30 
31## Key Issues
32 
33- **High CPU / partition imbalance**: Limit to 1.5–3 partitions per CPU core.
34- **Consumer disconnected**: Higher priority consumer took ownership. Expected during load balancing. Persistent issues without scaling indicate a problem.
35- **Connection sharing**: Reuse `EventHubClientBuilder` connections; avoid creating new clients per operation.
36 
37## Checkpointing (BlobCheckpointStore)
38 
39Package: `azure-messaging-eventhubs-checkpointstore-blob`
40 
41> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](auth-best-practices.md) for production patterns.
42 
43```java
44TokenCredential credential = new DefaultAzureCredentialBuilder().build();
45 
46BlobContainerAsyncClient blobClient = new BlobContainerClientBuilder()
47    .endpoint("https://<storage-account>.blob.core.windows.net/<checkpoint-container>")
48    .credential(credential)
49    .buildAsyncClient();
50 
51EventProcessorClient processor = new EventProcessorClientBuilder()
52    .credential("<your-namespace>.servicebus.windows.net", "<your-eventhub>", credential)
53    .consumerGroup("$Default")
54    .checkpointStore(new BlobCheckpointStore(blobClient))
55    .processEvent(eventContext -> {
56        // process event
57        eventContext.updateCheckpoint();
58    })
59    .buildEventProcessorClient();
60```
61 
62**Common issues:**
63- **Soft delete / blob versioning**: Disable both on the storage account — they cause delays during load balancing.
64- **HTTP 412/409 from storage**: Normal during partition ownership negotiation; not an error.
65- **Checkpoint frequency**: Call `updateCheckpoint()` per batch, not per event, to reduce storage calls.
66 
67## Filing Issues
68 
69Include: partition count, machine specs, instance count, max heap (`-Xmx`), average `EventData` size, traffic pattern, and DEBUG-level logs (±10 min from issue).
70