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.

Exception categories

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. The meaning and causes of an exception can vary depending on the type of messaging entity:

  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, System.UnauthorizedAccessException. General action: review your configuration and change if necessary.
  3. Transient exceptions (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). General action: retry the operation or notify users. Note that the RetryPolicy class in the client SDK can be configured to handle retries automatically. See Retry guidance for more information.
  4. 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:

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 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() 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 does 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 does 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 does not help.
MessagingEntityNotFoundException Entity associated with the operation does not exist or it has been deleted. Make sure the entity exists. Retry does 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 does 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 does not help.
SessionLockLostException Lock associated with this session is lost. Abort the MessageSession object. Retry does 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 256 KB. The server or service encountered an error during processing of the request. 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 does not help.
QuotaExceededException The messaging entity has reached its maximum allowable size, or the maximum number of connections to a namespace has been exceeded. 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.
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 does 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 does 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 does 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 does not help.
MessageSizeExceededException A message payload exceeds the 256-KB limit. The 256-KB 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 does not help.
TransactionException The ambient transaction (Transaction.Current) is invalid. It may have been completed or aborted. Inner exception may provide additional information. Retry does 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

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

Queues and topics

For queues and topics, this is often the size of the queue. The error message property contains 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).

Namespaces

For namespaces, QuotaExceededException can indicate that an application has exceeded the maximum number of connections to a namespace. For example:

Microsoft.ServiceBus.Messaging.QuotaExceededException: ConnectionsQuotaExceeded for namespace xxx.
<tracking-id-guid>_G12 ---> 
System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]: 
ConnectionsQuotaExceeded for namespace xxx.

Common causes

There are two common causes for this error: the dead-letter queue, and non-functioning message receivers.

  1. 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. You can use the FormatDeadLetterPath method to help format the dead-letter queue path.

  2. 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 are being written.

TimeoutException

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

You should check the value of the ServicePointManager.DefaultConnectionLimit property, as hitting this limit can also cause a TimeoutException.

Queues and topics

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.

Next steps

For the complete Service Bus .NET API reference, see the Azure .NET API reference.

To learn more about Service Bus, see the following articles: