Service-Level Troubleshooting
Covers connectivity, firewall, and network issues that apply regardless of SDK language.
Permanent Connectivity Issues
If the client cannot connect at all:
- Verify connection string — Get from Azure portal. For Event Hubs (Kafka endpoint) clients, also check
producer.config/consumer.config. - Check service outage — Azure status page
- 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.
- IP firewall — If enabled on namespace, ensure client IP is allowed.
- VNet / private endpoints — Confirm app runs in correct subnet. Check service endpoint and NSG rules.
- Proxy / SSL — Intercepting proxies can cause SSL handshake failures. Test with proxy disabled.
Quick Connectivity Test
# Test endpoint reachability (expect Atom feed XML on success)
curl -v https://<namespace>.servicebus.windows.net/
# Resolve namespace IP
nslookup <namespace>.servicebus.windows.netTransient Connectivity Issues
If connectivity is intermittent:
- Upgrade SDK — Use latest version; transient issues may already be fixed.
- Check dropped packets —
netstat -s(Linux) ornetsh interface ipv4 show subinterface(Windows). - Capture network traces — Use Wireshark or
tcpdumpfiltered on namespace IP. - Idle disconnect — Service disconnects idle AMQP connections. Clients auto-reconnect; this is expected.
WebSocket Configuration by Language
| Language | Setting |
|---|---|
| .NET | EventHubsTransportType.AmqpWebSockets / ServiceBusTransportType.AmqpWebSockets |
| Java | AmqpTransportType.AMQP_WEB_SOCKETS |
| Python | transport_type=TransportType.AmqpOverWebsocket |
| JavaScript | webSocketOptions in client constructor |
Authentication Checklist
| Issue | Fix |
|---|---|
| Invalid connection string | Re-copy from Azure portal |
| Expired SAS token | Regenerate or increase validity |
| Missing RBAC role | Assign the corresponding *Azure Event Hubs Data Owner/Sender/Receiver* or *Azure Service Bus Data Owner/Sender/Receiver* role |
| Managed Identity not configured | Enable system/user-assigned identity, assign role on namespace |
Sender Issues (All Languages)
- Batch >1MB fails — Service rejects batches over 1MB even with Premium large message support. Send large messages individually.
- Multiple partition keys in batch — Not allowed. Group messages by
partitionKey(orsessionId) into separate batches.
Receiver Issues (All Languages)
- Batch receive returns fewer messages — After the first message arrives, the receiver waits briefly (20ms–1s depending on SDK) for more.
maxWaitTimeonly controls the wait for the *first* message. - Lock lost before expiry — Can occur on AMQP link detach (transient network or 10-min idle timeout), not only when processing exceeds lock duration.
- Socket exhaustion — Treat clients as singletons. Each new client creates a new AMQP connection. Always close/dispose clients when done.