You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/event-hubs/event-hubs-messaging-exceptions.md
+48-22Lines changed: 48 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: Messaging exceptions for .NET - Azure Event Hubs | Microsoft Docs
2
+
title: Troubleshooting guide - Azure Event Hubs | Microsoft Docs
3
3
description: This article provides a list of Azure Event Hubs messaging exceptions and suggested actions.
4
4
services: event-hubs
5
5
documentationcenter: na
@@ -12,15 +12,18 @@ ms.topic: article
12
12
ms.tgt_pltfrm: na
13
13
ms.workload: na
14
14
ms.custom: seodec18
15
-
ms.date: 09/25/2019
15
+
ms.date: 12/03/2019
16
16
ms.author: shvija
17
17
18
18
---
19
-
# Event Hubs messaging exceptions - .NET
20
19
21
-
This article lists some of the .NET exceptions generated by the Azure Service Bus messaging .NET API library, which includes .NET Framework Event Hubs APIs. This reference is subject to change, so check back for updates.
20
+
# Troubleshooting guide for Azure Event Hubs
21
+
This article provides some of the .NET exceptions generated by Event Hubs .NET Framework APIs and also other tips for troubleshooting issues.
22
22
23
-
## Exception categories
23
+
## Event Hubs messaging exceptions - .NET
24
+
This section lists the .NET exceptions generated by .NET Framework APIs.
25
+
26
+
### Exception categories
24
27
25
28
The Event Hubs .NET APIs generate exceptions that can fall into the following categories, along with the associated action you can take to try to fix them.
26
29
@@ -29,15 +32,15 @@ The Event Hubs .NET APIs generate exceptions that can fall into the following ca
29
32
3. Transient exceptions: [Microsoft.ServiceBus.Messaging.MessagingException](/dotnet/api/microsoft.servicebus.messaging.messagingexception), [Microsoft.ServiceBus.Messaging.ServerBusyException](#serverbusyexception), [Microsoft.Azure.EventHubs.ServerBusyException](#serverbusyexception), [Microsoft.ServiceBus.Messaging.MessagingCommunicationException](/dotnet/api/microsoft.servicebus.messaging.messagingcommunicationexception). General action: retry the operation or notify users.
30
33
4. Other exceptions: [System.Transactions.TransactionException](https://msdn.microsoft.com/library/system.transactions.transactionexception.aspx), [System.TimeoutException](#timeoutexception), [Microsoft.ServiceBus.Messaging.MessageLockLostException](/dotnet/api/microsoft.servicebus.messaging.messagelocklostexception), [Microsoft.ServiceBus.Messaging.SessionLockLostException](/dotnet/api/microsoft.servicebus.messaging.sessionlocklostexception). General action: specific to the exception type; refer to the table in the following section.
31
34
32
-
## Exception types
35
+
###Exception types
33
36
The following table lists messaging exception types, and their causes, and notes suggested action you can take.
34
37
35
38
| Exception Type | Description/Cause/Examples | Suggested Action | Note on automatic/immediate retry |
|[TimeoutException](https://msdn.microsoft.com/library/system.timeoutexception.aspx)|The server did not respond to the requested operation within the specified time, which is controlled by [OperationTimeout](/dotnet/api/microsoft.servicebus.messaging.messagingfactorysettings). The server may have completed the requested operation. This exception can happen due to network or other infrastructure delays. |Check the system state for consistency and retry if necessary.<br /> See [TimeoutException](#timeoutexception). | Retry might help in some cases; add retry logic to code. |
38
-
|[InvalidOperationException](https://msdn.microsoft.com/library/system.invalidoperationexception.aspx)|The requested user operation is not allowed within the server or service. See the exception message for details. For example, [Complete](/dotnet/api/microsoft.servicebus.messaging.brokeredmessage) generates this exception if the message was received in [ReceiveAndDelete](/dotnet/api/microsoft.servicebus.messaging.receivemode) mode. | Check the code and the documentation. Make sure the requested operation is valid. | Retry will not help. |
39
-
|[OperationCanceledException](https://msdn.microsoft.com/library/system.operationcanceledexception.aspx)| An attempt is made to invoke an operation on an object that has already been closed, aborted, or disposed. In rare cases, the ambient transaction is already disposed. | Check the code and make sure it does not invoke operations on a disposed object. | Retry will not help. |
40
-
|[UnauthorizedAccessException](https://msdn.microsoft.com/library/system.unauthorizedaccessexception.aspx)| The [TokenProvider](/dotnet/api/microsoft.servicebus.tokenprovider) object could not acquire a token, the token is invalid, or the token does not contain the claims required to perform the operation. | Make sure the token provider is created with the correct values. Check the configuration of the Access Control service. | Retry might help in some cases; add retry logic to code. |
40
+
|[TimeoutException](https://msdn.microsoft.com/library/system.timeoutexception.aspx)|The server didn't respond to the requested operation within the specified time, which is controlled by [OperationTimeout](/dotnet/api/microsoft.servicebus.messaging.messagingfactorysettings). The server may have completed the requested operation. This exception can happen because of network or other infrastructure delays. |Check the system state for consistency and retry if necessary.<br /> See [TimeoutException](#timeoutexception). | Retry might help in some cases; add retry logic to code. |
41
+
|[InvalidOperationException](https://msdn.microsoft.com/library/system.invalidoperationexception.aspx)|The requested user operation isn't allowed within the server or service. See the exception message for details. For example, [Complete](/dotnet/api/microsoft.servicebus.messaging.brokeredmessage) generates this exception if the message was received in [ReceiveAndDelete](/dotnet/api/microsoft.servicebus.messaging.receivemode) mode. | Check the code and the documentation. Make sure the requested operation is valid. | Retry won't help. |
42
+
|[OperationCanceledException](https://msdn.microsoft.com/library/system.operationcanceledexception.aspx)| An attempt is made to invoke an operation on an object that has already been closed, aborted, or disposed. In rare cases, the ambient transaction is already disposed. | Check the code and make sure it doesn't invoke operations on a disposed object. | Retry won't help. |
43
+
|[UnauthorizedAccessException](https://msdn.microsoft.com/library/system.unauthorizedaccessexception.aspx)| The [TokenProvider](/dotnet/api/microsoft.servicebus.tokenprovider) object couldn't acquire a token, the token is invalid, or the token doesn't contain the claims required to do the operation. | Make sure the token provider is created with the correct values. Check the configuration of the Access Control Service. | Retry might help in some cases; add retry logic to code. |
41
44
|[ArgumentException](https://msdn.microsoft.com/library/system.argumentexception.aspx)<br /> [ArgumentNullException](https://msdn.microsoft.com/library/system.argumentnullexception.aspx)<br />[ArgumentOutOfRangeException](https://msdn.microsoft.com/library/system.argumentoutofrangeexception.aspx)| One or more arguments supplied to the method are invalid. The URI supplied to [NamespaceManager](/dotnet/api/microsoft.servicebus.namespacemanager) or [Create](/dotnet/api/microsoft.servicebus.messaging.messagingfactory) contains path segment(s). The URI scheme supplied to [NamespaceManager](/dotnet/api/microsoft.servicebus.namespacemanager) or [Create](/dotnet/api/microsoft.servicebus.messaging.messagingfactory) is invalid. The property value is larger than 32 KB. | Check the calling code and make sure the arguments are correct. | Retry will not help. |
42
45
|[Microsoft.ServiceBus.Messaging MessagingEntityNotFoundException](/dotnet/api/microsoft.servicebus.messaging.messagingentitynotfoundexception) <br /><br/> [Microsoft.Azure.EventHubs MessagingEntityNotFoundException](/dotnet/api/microsoft.azure.eventhubs.messagingentitynotfoundexception)| Entity associated with the operation does not exist or it has been deleted. | Make sure the entity exists. | Retry will not help. |
43
46
|[MessagingCommunicationException](/dotnet/api/microsoft.servicebus.messaging.messagingcommunicationexception)| Client is not able to establish a connection to Event Hub. |Make sure the supplied host name is correct and the host is reachable. | Retry might help if there are intermittent connectivity issues. |
@@ -46,56 +49,79 @@ The following table lists messaging exception types, and their causes, and notes
46
49
|[MessagingEntityAlreadyExistsException](/dotnet/api/microsoft.servicebus.messaging.messagingentityalreadyexistsexception)| Attempt to create an entity with a name that is already used by another entity in that service namespace. | Delete the existing entity or choose a different name for the entity to be created. | Retry will not help. |
47
50
|[QuotaExceededException](/dotnet/api/microsoft.servicebus.messaging.quotaexceededexception)| The messaging entity has reached its maximum allowable size. This exception can happen if the maximum number of receivers (which is 5) has already been opened on a per-consumer group level. | Create space in the entity by receiving messages from the entity or its subqueues. <br /> See [QuotaExceededException](#quotaexceededexception)| Retry might help if messages have been removed in the meantime. |
48
51
|[MessagingEntityDisabledException](/dotnet/api/microsoft.servicebus.messaging.messagingentitydisabledexception)| Request for a runtime operation on a disabled entity. |Activate the entity. | Retry might help if the entity has been activated in the interim. |
49
-
|[Microsoft.ServiceBus.Messaging MessageSizeExceededException](/dotnet/api/microsoft.servicebus.messaging.messagesizeexceededexception) <br /><br/> [Microsoft.Azure.EventHubs MessageSizeExceededException](/dotnet/api/microsoft.azure.eventhubs.messagesizeexceededexception)| A message payload exceeds the 1MB limit. This 1MB limit is for the total message, which can include system properties and any .NET overhead. | Reduce the size of the message payload, then retry the operation. |Retry will not help. |
52
+
|[Microsoft.ServiceBus.Messaging MessageSizeExceededException](/dotnet/api/microsoft.servicebus.messaging.messagesizeexceededexception) <br /><br/> [Microsoft.Azure.EventHubs MessageSizeExceededException](/dotnet/api/microsoft.azure.eventhubs.messagesizeexceededexception)| A message payload exceeds the 1-MB limit. This 1-MB limit is for the total message, which can include system properties and any .NET overhead. | Reduce the size of the message payload, then retry the operation. |Retry will not help. |
50
53
51
-
## QuotaExceededException
54
+
###QuotaExceededException
52
55
[QuotaExceededException](/dotnet/api/microsoft.servicebus.messaging.quotaexceededexception) indicates that a quota for a specific entity has been exceeded.
53
56
54
57
This exception can happen if the maximum number of receivers (5) has already been opened on a per-consumer group level.
55
58
56
-
### Event Hubs
59
+
####Event Hubs
57
60
Event Hubs has a limit of 20 consumer groups per Event Hub. When you attempt to create more, you receive a [QuotaExceededException](/dotnet/api/microsoft.servicebus.messaging.quotaexceededexception).
58
61
59
-
## TimeoutException
62
+
###TimeoutException
60
63
A [TimeoutException](https://msdn.microsoft.com/library/system.timeoutexception.aspx) indicates that a user-initiated operation is taking longer than the operation timeout.
61
64
62
65
For Event Hubs, the timeout is specified either as part of the connection string, or through [ServiceBusConnectionStringBuilder](/dotnet/api/microsoft.servicebus.servicebusconnectionstringbuilder). The error message itself might vary, but it always contains the timeout value specified for the current operation.
63
66
64
-
### Common causes
67
+
####Common causes
65
68
There are two common causes for this error: incorrect configuration, or a transient service error.
66
69
67
70
1.**Incorrect configuration**
68
-
The operation timeout might be too small for the operational condition. The default value for the operation timeout in the client SDK is 60 seconds. Check to see if your code has the value set to something too small. Note that the condition of the network and CPU usage can affect the time it takes for a particular operation to complete, so the operation timeout should not be set to a small value.
71
+
The operation timeout might be too small for the operational condition. The default value for the operation timeout in the client SDK is 60 seconds. Check to see if your code has the value set to something too small. The condition of the network and CPU usage can affect the time it takes for a particular operation to complete, so the operation timeout should not be set to a small value.
69
72
2.**Transient service error**
70
73
Sometimes the Event Hubs service can experience delays in processing requests; for example, during periods of high traffic. In such cases, you can retry your operation after a delay, until the operation is successful. If the same operation still fails after multiple attempts, visit the [Azure service status site](https://azure.microsoft.com/status/) to see if there are any known service outages.
71
74
72
-
## ServerBusyException
75
+
###ServerBusyException
73
76
74
77
A [Microsoft.ServiceBus.Messaging.ServerBusyException](/dotnet/api/microsoft.servicebus.messaging.serverbusyexception) or [Microsoft.Azure.EventHubs.ServerBusyException](/dotnet/api/microsoft.azure.eventhubs.serverbusyexception) indicates that a server is overloaded. There are two relevant error codes for this exception.
75
78
76
-
### Error code 50002
79
+
####Error code 50002
77
80
78
81
This error can occur for one of two reasons:
79
82
80
-
1. The load is not evenly distributed across all partitions on the event hub, and one partition hits the local throughput unit limitation.
83
+
1. The load isn't evenly distributed across all partitions on the event hub, and one partition hits the local throughput unit limitation.
81
84
82
85
Resolution: Revising the partition distribution strategy or trying [EventHubClient.Send(eventDataWithOutPartitionKey)](/dotnet/api/microsoft.servicebus.messaging.eventhubclient) might help.
83
86
84
-
2. The Event Hubs namespace does not have sufficient throughput units (you can check the **Metrics** screen in the Event Hubs namespace window in the [Azure portal](https://portal.azure.com) to confirm). The portal shows aggregated (1 minute) information, but we measure the throughput in real time – so it is only an estimate.
87
+
2. The Event Hubs namespace doesn't have sufficient throughput units (you can check the **Metrics** screen in the Event Hubs namespace window in the [Azure portal](https://portal.azure.com) to confirm). The portal shows aggregated (1 minute) information, but we measure the throughput in real time – so it's only an estimate.
85
88
86
89
Resolution: Increasing the throughput units on the namespace can help. You can do this operation on the portal, in the **Scale** window of the Event Hubs namespace screen. Or, you can use [Auto-inflate](event-hubs-auto-inflate.md).
87
90
88
-
### Error code 50001
91
+
####Error code 50001
89
92
90
93
This error should rarely occur. It happens when the container running code for your namespace is low on CPU – not more than a few seconds before the Event Hubs load balancer begins.
91
94
92
-
### Limit on calls to the GetRuntimeInformation method
95
+
####Limit on calls to the GetRuntimeInformation method
93
96
Azure Event Hubs supports up to 50 calls per second to the GetRuntimeInfo per second. You may receive an exception similar to the following one once the limit is reached:
94
97
95
98
```
96
99
ExceptionId: 00000000000-00000-0000-a48a-9c908fbe84f6-ServerBusyException: The request was terminated because the namespace 75248:aaa-default-eventhub-ns-prodb2b is being throttled. Error code : 50001. Please wait 10 seconds and try again.
97
100
```
98
101
102
+
## Connectivity, certificate, or timeout issues
103
+
The following steps may help you with troubleshooting connectivity/certificate/timeout issues for all services under *.servicebus.windows.net.
104
+
105
+
- Browse to or [wget](https://www.gnu.org/software/wget/)`https://sbwagn2.servicebus.windows.net/`. It helps with checking whether you have IP filtering or virtual network or certificate chain issues (most common when using java SDK).
106
+
- Run the following command to check if any port is blocked on the firewall. Depending on the library you use, other ports are also used. For example: 443, 5672, 9354.
107
+
108
+
```powershell
109
+
tnc sbwagn2.servicebus.windows.net -port 5671
110
+
```
111
+
112
+
On Linux:
113
+
114
+
```shell
115
+
telnet sbwagn2.servicebus.windows.net 5671
116
+
```
117
+
- When there are intermittent connectivity issues, run the following command to check if there are any dropped packets. Keep it running for approximately 1 minute to know if the connections are partially blocked. You can download the `psping` tool from [here](/sysinternals/downloads/psping).
0 commit comments