Azure Event Hubs SDK — Java

Package: azure-messaging-eventhubs | README | Full Troubleshooting Guide

⚠️ Note: The detailed Java troubleshooting guide has moved to Microsoft Learn.

Common Errors

Exception	Cause	Fix
AmqpException (connection:forced)	Idle connection disconnected	Auto-recovers; no action needed
AmqpException (unauthorized-access)	Bad credentials or missing permissions	Verify connection string, SAS, or RBAC roles
AmqpException (resource-limit-exceeded)	Too many concurrent receivers	Reduce receiver count or upgrade tier
OperationTimeoutException	Network issue or throttling	Check firewall, try AMQP over WebSockets (port 443)

Enable Logging

Configure via SLF4J. Add logback-classic dependency and set level for com.azure.messaging.eventhubs:

<logger name="com.azure.messaging.eventhubs" level="DEBUG"/>

For AMQP frame tracing:

<logger name="com.azure.core.amqp" level="DEBUG"/>

See Java SDK logging docs for details.

Key Issues

• High CPU / partition imbalance: Limit to 1.5–3 partitions per CPU core.
• Consumer disconnected: Higher priority consumer took ownership. Expected during load balancing. Persistent issues without scaling indicate a problem.
• Connection sharing: Reuse EventHubClientBuilder connections; avoid creating new clients per operation.

Checkpointing (BlobCheckpointStore)

Package: azure-messaging-eventhubs-checkpointstore-blob

Auth: DefaultAzureCredential is for local development. See auth-best-practices.md for production patterns.

TokenCredential credential = new DefaultAzureCredentialBuilder().build();

BlobContainerAsyncClient blobClient = new BlobContainerClientBuilder()