1# Service-Level Troubleshooting
2 
3Covers connectivity, firewall, and network issues that apply regardless of SDK language.
4 
5## Permanent Connectivity Issues
6 
7If the client **cannot connect at all**:
8 
91. **Verify connection string** — Get from Azure portal. For **Event Hubs (Kafka endpoint)** clients, also check `producer.config` / `consumer.config`.
102. **Check service outage** — [Azure status page](https://azure.status.microsoft/status)
113. **Firewall / ports** — Open AMQP 5671 and 5672, HTTPS 443. For **Event Hubs (Kafka endpoint)** only, also open Kafka 9093. Use WebSockets (port 443) as fallback.
124. **IP firewall** — If enabled on namespace, ensure client IP is allowed.
135. **VNet / private endpoints** — Confirm app runs in correct subnet. Check service endpoint and NSG rules.
146. **Proxy / SSL** — Intercepting proxies can cause SSL handshake failures. Test with proxy disabled.
15 
16### Quick Connectivity Test
17 
18```bash
19# Test endpoint reachability (expect Atom feed XML on success)
20curl -v https://<namespace>.servicebus.windows.net/
21 
22# Resolve namespace IP
23nslookup <namespace>.servicebus.windows.net
24```
25 
26## Transient Connectivity Issues
27 
28If connectivity is **intermittent**:
29 
301. **Upgrade SDK** — Use latest version; transient issues may already be fixed.
312. **Check dropped packets** — `netstat -s` (Linux) or `netsh interface ipv4 show subinterface` (Windows).
323. **Capture network traces** — Use Wireshark or `tcpdump` filtered on namespace IP.
334. **Idle disconnect** — Service disconnects idle AMQP connections. Clients auto-reconnect; this is expected.
34 
35## WebSocket Configuration by Language
36 
37| Language | Setting |
38|----------|---------|
39| .NET | `EventHubsTransportType.AmqpWebSockets` / `ServiceBusTransportType.AmqpWebSockets` |
40| Java | `AmqpTransportType.AMQP_WEB_SOCKETS` |
41| Python | `transport_type=TransportType.AmqpOverWebsocket` |
42| JavaScript | `webSocketOptions` in client constructor |
43 
44## Authentication Checklist
45 
46| Issue | Fix |
47|-------|-----|
48| Invalid connection string | Re-copy from Azure portal |
49| Expired SAS token | Regenerate or increase validity |
50| Missing RBAC role | Assign the corresponding *Azure Event Hubs Data Owner/Sender/Receiver* or *Azure Service Bus Data Owner/Sender/Receiver* role |
51| Managed Identity not configured | Enable system/user-assigned identity, assign role on namespace |
52 
53## Sender Issues (All Languages)
54 
55- **Batch >1MB fails** — Service rejects batches over 1MB even with Premium large message support. Send large messages individually.
56- **Multiple partition keys in batch** — Not allowed. Group messages by `partitionKey` (or `sessionId`) into separate batches.
57 
58## Receiver Issues (All Languages)
59 
60- **Batch receive returns fewer messages** — After the first message arrives, the receiver waits briefly (20ms–1s depending on SDK) for more. `maxWaitTime` only controls the wait for the *first* message.
61- **Lock lost before expiry** — Can occur on AMQP link detach (transient network or 10-min idle timeout), not only when processing exceeds lock duration.
62- **Socket exhaustion** — Treat clients as singletons. Each new client creates a new AMQP connection. Always close/dispose clients when done.
63 
64## Further Reading
65 
66- [Event Hubs troubleshooting guide](https://learn.microsoft.com/azure/event-hubs/troubleshooting-guide)
67- [Service Bus troubleshooting guide](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-troubleshooting-guide)
68- [Event Hubs quotas and limits](https://learn.microsoft.com/azure/event-hubs/event-hubs-quotas)
69- [Service Bus quotas and limits](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-quotas)
70- [Event Hubs AMQP troubleshooting](https://learn.microsoft.com/azure/event-hubs/event-hubs-amqp-troubleshoot)
71- [Service Bus AMQP troubleshooting](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-amqp-troubleshoot)
72- [Event Hubs IP addresses and service tags](https://learn.microsoft.com/azure/event-hubs/troubleshooting-guide#what-ip-addresses-do-i-need-to-allow)
73- [Service Bus IP addresses](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-faq#what-ip-addresses-do-i-need-to-add-to-allowlist-)
74