1# Azure Event Hubs SDK — JavaScript
2 
3Package: `@azure/event-hubs` | [README](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/) | [Full Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/TROUBLESHOOTING.md)
4 
5## Common Errors
6 
7| Error | Code | Fix |
8|-------|------|-----|
9| `MessagingError` (connection:forced) | Idle disconnect | Auto-recovers; no action needed |
10| `MessagingError` (Unauthorized) | Bad credentials | Verify connection string, SAS, or RBAC roles |
11| `MessagingError` (retryable: true) | Transient issue | Auto-retried per `RetryOptions`. If surfaced, all retries exhausted |
12 
13`MessagingError` fields: `name`, `code`, `retryable`, `info`, `address`, `errno`, `port`, `syscall`.
14 
15## Enable Logging
16 
17```bash
18# All SDK logs
19export AZURE_LOG_LEVEL=verbose
20 
21# Or use DEBUG for granular control
22export DEBUG=azure*,rhea*
23 
24# Errors only
25export DEBUG=azure:*:(error|warning),rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow
26```
27 
28Browser:
29```javascript
30localStorage.debug = "azure:*:info";
31```
32 
33## Key Issues
34 
35- **Socket exhaustion**: Treat clients as singletons. Each new client creates a new AMQP connection/socket. Always call `close()`.
36- **412 precondition failures**: Normal during subscription partition ownership negotiation.
37- **Partition ownership churn**: Expected when scaling instances. Should stabilize within minutes.
38- **High CPU**: Limit to 1.5–3 partitions per CPU core.
39- **Subscription stops receiving**: Often a symptom of an underlying race condition during error recovery. File a GitHub issue with DEBUG logs.
40- **WebSockets**: Pass `webSocketOptions` to client constructor to connect over port 443.
41 
42## Checkpointing (BlobCheckpointStore)
43 
44Package: `@azure/eventhubs-checkpointstore-blob`
45 
46> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](auth-best-practices.md) for production patterns.
47 
48```javascript
49const { BlobCheckpointStore } = require("@azure/eventhubs-checkpointstore-blob");
50const { BlobServiceClient } = require("@azure/storage-blob");
51 
52const containerClient = new BlobServiceClient(storageEndpoint, credential)
53  .getContainerClient("checkpointstore");
54const checkpointStore = new BlobCheckpointStore(containerClient);
55 
56const consumerClient = new EventHubConsumerClient(
57  consumerGroup, fullyQualifiedNamespace, eventHubName, credential, checkpointStore
58);
59```
60 
61**Common issues:**
62- **Soft delete / blob versioning**: Disable both on the storage account — they cause delays during load balancing.
63- **412 precondition failures**: Normal during partition ownership negotiation; not an error.
64- **Checkpoint frequency**: Call `updateCheckpoint()` per batch, not per event, to reduce storage calls.
65