Event Hubs messaging exceptions - .NET

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.

Exception categories

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.

  1. User coding error: System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException. General action: try to fix the code before proceeding.
  2. Setup/configuration error: Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, Microsoft.Azure.EventHubs.MessagingEntityNotFoundException, System.UnauthorizedAccessException. General action: review your configuration and change if necessary.
  3. Transient exceptions: Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.Azure.EventHubs.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException. General action: retry the operation or notify users.
  4. Other exceptions: System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException. General action: specific to the exception type; refer to the table in the following section.

Exception types

The following table lists messaging exception types, and their causes, and notes suggested action you can take.

Exception Type Description/Cause/Examples Suggested Action Note on automatic/immediate retry
TimeoutException The server did not respond to the requested operation within the specified time, which is controlled by OperationTimeout. 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.
See TimeoutException.
Retry might help in some cases; add retry logic to code.
InvalidOperationException The requested user operation is not allowed within the server or service. See the exception message for details. For example, Complete generates this exception if the message was received in ReceiveAndDelete mode. Check the code and the documentation. Make sure the requested operation is valid. Retry will not help.
OperationCanceledException 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.
UnauthorizedAccessException The 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.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException
One or more arguments supplied to the method are invalid. The URI supplied to NamespaceManager or Create contains path segment(s). The URI scheme supplied to NamespaceManager or Create 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.
Microsoft.ServiceBus.Messaging MessagingEntityNotFoundException

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.
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.
Microsoft.ServiceBus.Messaging ServerBusyException

Microsoft.Azure.EventHubs ServerBusyException
Service is not able to process the request at this time. Client can wait for a period of time, then retry the operation.
See ServerBusyException.
Client may retry after certain interval. If a retry results in a different exception, check retry behavior of that exception.
MessagingException Generic messaging exception that may be thrown in the following cases: An attempt is made to create a QueueClient using a name or path that belongs to a different entity type (for example, a topic). An attempt is made to send a message larger than 1 MB. The server or service encountered an error during processing of the request. See the exception message for details. This exception is usually a transient exception. Check the code and ensure that only serializable objects are used for the message body (or use a custom serializer). Check the documentation for the supported value types of the properties and only use supported types. Check the IsTransient property. If it is true, you can retry the operation. Retry behavior is undefined and might not help.
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.
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.
See QuotaExceededException
Retry might help if messages have been removed in the meantime.
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.
Microsoft.ServiceBus.Messaging MessageSizeExceededException

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.

QuotaExceededException

QuotaExceededException indicates that a quota for a specific entity has been exceeded.

This exception can happen if the maximum number of receivers (5) has already been opened on a per-consumer group level.

Event Hubs

Event Hubs has a limit of 20 consumer groups per Event Hub. When you attempt to create more, you receive a QuotaExceededException.

TimeoutException

A TimeoutException indicates that a user-initiated operation is taking longer than the operation timeout.

For Event Hubs, the timeout is specified either as part of the connection string, or through ServiceBusConnectionStringBuilder. The error message itself might vary, but it always contains the timeout value specified for the current operation.

Common causes

There are two common causes for this error: incorrect configuration, or a transient service error.

  1. Incorrect configuration 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.
  2. Transient service error 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 to see if there are any known service outages.

ServerBusyException

A Microsoft.ServiceBus.Messaging.ServerBusyException or Microsoft.Azure.EventHubs.ServerBusyException indicates that a server is overloaded. There are two relevant error codes for this exception.

Error code 50002

This error can occur for one of two reasons:

  1. The load is not evenly distributed across all partitions on the event hub, and one partition hits the local throughput unit limitation.

    Resolution: Revising the partition distribution strategy or trying EventHubClient.Send(eventDataWithOutPartitionKey) might help.

  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 to confirm). The portal shows aggregated (1 minute) information, but we measure the throughput in real time – so it is only an estimate.

    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.

Error code 50001

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.

Limit on calls to the GetRuntimeInformation method

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:

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.

Next steps

You can learn more about Event Hubs by visiting the following links: