Service Bus messaging exceptions
This article lists some exceptions generated by the Microsoft Azure Service Bus messaging APIs. This reference is subject to change, so check back for updates.
The messaging APIs generate exceptions that can fall into the following categories, along with the associated action you can take to try to fix them. Note that the meaning and causes of an exception can vary depending on the type of messaging entity (relays, queues/topics, Event Hubs):
User coding error (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). General action: try to fix the code before proceeding.
Setup/configuration error (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. General action: review your configuration and change if necessary.
Transient exceptions (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). General action: retry the operation or notify users.
Other exceptions (System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException). General action: specific to the exception type; please refer to the table in the following section.
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 can happen due to network or other infrastructure delays.||Check the system state for consistency and retry if necessary. See Timeout exceptions.||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 will generate 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.|
|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 32KB.
|Check the calling code and make sure the arguments are correct.||Retry will not help.|
|MessagingEntityNotFoundException||Entity associated with the operation does not exist or it has been deleted.||Make sure the entity exists.||Retry will not help.|
|MessageNotFoundException||Attempt to receive a message with a particular sequence number. This message is not found.||Make sure the message has not been received already. Check the deadletter queue to see if the message has been deadlettered.||Retry will not help.|
|MessagingCommunicationException||Client is not able to establish a connection to Service Bus.||Make sure the supplied host name is correct and the host is reachable.||Retry might help if there are intermittent connectivity issues.|
|ServerBusyException||Service is not able to process the request at this time.||Client can wait for a period of time, then retry the operation.||Client may retry after certain interval. If a retry results in a different exception, check retry behavior of that exception.|
|MessageLockLostException||Lock token associated with the message has expired, or the lock token is not found.||Dispose the message.||Retry will not help.|
|SessionLockLostException||Lock associated with this session is lost.||Abort the MessageSession object.||Retry will not help.|
|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 256KB. The server or service encountered an error during processing of the request. Please see the exception message for details. This 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.||Create space in the entity by receiving messages from the entity or its sub-queues. See QuotaExceededException.||Retry might help if messages have been removed in the meantime.|
|RuleActionException||Service Bus returns this exception if you attempt to create an invalid rule action. Service Bus attaches this exception to a deadlettered message if an error occurs while processing the rule action for that message.||Check the rule action for correctness.||Retry will not help.|
|FilterException||Service Bus returns this exception if you attempt to create an invalid filter. Service Bus attaches this exception to a deadlettered message if an error occurred while processing the filter for that message.||Check the filter for correctness.||Retry will not help.|
|SessionCannotBeLockedException||Attempt to accept a session with a specific session ID, but the session is currently locked by another client.||Make sure the session is unlocked by other clients.||Retry might help if the session has been released in the interim.|
|TransactionSizeExceededException||Too many operations are part of the transaction.||Reduce the number of operations that are part of this transaction.||Retry will not help.|
|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.|
|NoMatchingSubscriptionException||Service Bus returns this exception if you send a message to a topic that has pre-filtering enabled and none of the filters match.||Make sure at least one filter matches.||Retry will not help.|
|MessageSizeExceededException||A message payload exceeds the 256K limit. Note that the 256k limit is the total message size, which can include system properties and any .NET overhead.||Reduce the size of the message payload, then retry the operation.||Retry will not help.|
|TransactionException||The ambient transaction (Transaction.Current) is invalid. It may have been completed or aborted. Inner exception may provide additional information.||Retry will not help.|
|TransactionInDoubtException||An operation is attempted on a transaction that is in doubt, or an attempt is made to commit the transaction and the transaction becomes in doubt.||Your application must handle this exception (as a special case), as the transaction may have already been committed.||-|
QuotaExceededException indicates that a quota for a specific entity has been exceeded.
For queues and topics, this is often the size of the queue. The error message property will contain further details, as in the following example:
Microsoft.ServiceBus.Messaging.QuotaExceededException Message: The maximum entity size has been reached or exceeded for Topic: ‘xxx-xxx-xxx’. Size of entity in bytes:1073742326, Max entity size in bytes: 1073741824..TrackingId:xxxxxxxxxxxxxxxxxxxxxxxxxx, TimeStamp:3/15/2013 7:50:18 AM
The message states that the topic exceeded its size limit, in this case 1 GB (the default size limit).
There are two common causes for this error: the dead-letter queue, and non-functioning message receivers.
Dead-letter queue A reader is failing to complete messages and the messages are returned to the queue/topic when the lock expires. This can happen if the reader encounters an exception that prevents it from calling BrokeredMessage.Complete. After a message has been read 10 times, it moves to the dead-letter queue by default. This behavior is controlled by the QueueDescription.MaxDeliveryCount property and has a default value of 10. As messages pile up in the dead letter queue, they take up space.
To resolve the issue, read and complete the messages from the dead-letter queue, as you would from any other queue. The QueueClient class even contains a FormatDeadLetterPath method to help format the dead-letter queue path.
Receiver stopped A receiver has stopped receiving messages from a queue or subscription. The way to identify this is to look at the QueueDescription.MessageCountDetails property, which shows the full breakdown of the messages. If the ActiveMessageCount property is high or growing, then the messages are not being read as fast as they're being written.
Event Hubs has a limit of 20 consumer groups per Event Hub. When you attempt to create more, you receive a QuotaExceededException.
For the Service Bus relay, this exception wraps the System.ServiceModel.QuotaExceededException, indicating that the maximum number of listeners has been exceeded for this endpoint. This is indicated in the MaximumListenersPerEndpoint value of the exception message.
A TimeoutException indicates that a user-initiated operation is taking longer than the operation timeout.
For queues and topics, the timeout is specified either in the MessagingFactorySettings.OperationTimeout property, 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.
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.
For the Service Bus relay, you might receive timeout exceptions when first opening a relay sender connection. There are two common causes for this exception:
- The OpenTimeout value might be too small (even a fraction of a second).
- The on-premises relay listener(s) may not be responsive (or might encounter firewall rules issues prohibiting the listeners from accepting new client connections), and the OpenTimeout value is less than about 20 seconds.
'System.TimeoutException’: The operation did not complete within the allotted timeout of 00:00:10. The time allotted to this operation may have been a portion of a longer timeout.
There are two common causes for this error: incorrect configuration, or a transient service error.
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 very small value.
Transient service error Sometimes the Service Bus 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, please visit the Azure service status site to see if there are any known service outages.
For the complete Service Bus and Event Hubs .NET API reference, see the Azure reference on MSDN.
To learn more about Service Bus, see the following topics.