Edit

Share via

Service Bus messaging exceptions (deprecated)

  • Article

This article lists the .NET exceptions generated by .NET Framework APIs.

On 30 September 2026, we'll retire the Azure Service Bus SDK libraries WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus, and com.microsoft.azure.servicebus, which don't conform to Azure SDK guidelines. We'll also end support of the SBMP protocol, so you'll no longer be able to use this protocol after 30 September 2026. Migrate to the latest Azure SDK libraries, which offer critical security updates and improved capabilities, before that date.

Although the older libraries can still be used beyond 30 September 2026, they'll no longer receive official support and updates from Microsoft. For more information, see the support retirement announcement.

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. The RetryPolicy class in the client SDK can be configured to handle retries automatically. For more information, see Retry guidance.
  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:

Important

  • Azure Service Bus doesn't retry an operation in case of an exception when the operation is in a transaction scope.
  • For retry guidance specific to Azure Service Bus, see Retry guidance for Service Bus.

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 didn't respond to the requested operation within the specified time, which is controlled by OperationTimeout. The server might have completed the requested operation. It can happen because of 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 isn't 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 doesn't 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 doesn't invoke operations on a disposed object. Retry doesn't help.
UnauthorizedAccessException The 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.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 One or more arguments supplied to the method are invalid.
The URI supplied to NamespaceManager or Create contains path segments.
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 doesn't help.
MessagingEntityNotFoundException Entity associated with the operation doesn't exist or it has been deleted. Make sure the entity exists. Retry doesn't help.
MessageNotFoundException Attempt to receive a message with a particular sequence number. This message isn't found. Make sure the message hasn't been received already. Check the deadletter queue to see if the message has been deadlettered. Retry doesn't help.
MessagingCommunicationException Client isn't able to establish a connection to Service Bus. Make sure the supplied host name is correct and the host is reachable.

If your code runs in an environment with a firewall/proxy, ensure that the traffic to the Service Bus domain/IP address and ports isn't blocked.

 Retry might help if there are intermittent connectivity issues.
ServerBusyException Service isn't able to process the request at this time. Client can wait for a period of time, then retry the operation. Client might retry after certain interval. If a retry results in a different exception, check retry behavior of that exception.
MessagingException Generic messaging exception that might 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. It's usually a transient exception.

The request was terminated because the entity is being throttled. Error code: 50001, 50002, 50008.

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's true, you can retry the operation.

If the exception is due to throttling, wait for a few seconds and retry the operation again. Retry behavior is undefined and might not help in other scenarios.
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 doesn't 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 doesn't 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 doesn't 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 doesn't 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 prefiltering enabled and none of the filters match. Make sure at least one filter matches. Retry doesn't 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 doesn't help.
TransactionException The ambient transaction (Transaction.Current) is invalid. It might have been completed or aborted. Inner exception might provide additional information. Retry doesn't 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 might have already been committed. -

QuotaExceededException

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

Note

For Service Bus quotas, see Quotas.

Queues and topics

For queues and topics, it's 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 nonfunctioning 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. It 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 aren't being read as fast as they're 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.

Timeouts are expected to happen during or in-between maintenance operations such as Service Bus service updates (or) OS updates on resources that run the service. During OS updates, entities are moved around and nodes are updated or rebooted, which can cause timeouts. For service level agreement (SLA) details for the Azure Service Bus service, see SLA for Service Bus.

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.

MessageLockLostException

Cause

The MessageLockLostException is thrown when a message is received using the PeekLock Receive mode and the lock held by the client expires on the service side.

The lock on a message might expire due to various reasons:

  • The lock timer has expired before it was renewed by the client application.
  • The client application acquired the lock, saved it to a persistent store and then restarted. Once it restarted, the client application looked at the inflight messages and tried to complete these.

You might also receive this exception in the following scenarios:

  • Service Update
  • OS update
  • Changing properties on the entity (queue, topic, subscription) while holding the lock.

Resolution

When a client application receives MessageLockLostException, it can no longer process the message. The client application might optionally consider logging the exception for analysis, but the client must dispose off the message.

Since the lock on the message has expired, it would go back on the Queue (or Subscription) and can be processed by the next client application that calls receive.

If the MaxDeliveryCount has exceeded, then the message might be moved to the DeadLetterQueue.

SessionLockLostException

Cause

The SessionLockLostException is thrown when a session is accepted and the lock held by the client expires on the service side.

The lock on a session might expire due to various reasons:

  • The lock timer has expired before it was renewed by the client application.
  • The client application acquired the lock, saved it to a persistent store and then restarted. Once it restarted, the client application looked at the inflight sessions and tried to process the messages in those sessions.

You might also receive this exception in the following scenarios:

  • Service Update
  • OS update
  • Changing properties on the entity (queue, topic, subscription) while holding the lock.

Resolution

When a client application receives SessionLockLostException, it can no longer process the messages on the session. The client application might consider logging the exception for analysis, but the client must dispose off the message.

Since the lock on the session has expired, it would go back on the Queue (or Subscription) and can be locked by the next client application that accepts the session. Since the session lock is held by a single client application at any given time, the in-order processing is guaranteed.

SocketException

Cause

A SocketException is thrown in the following cases:

  • When a connection attempt fails because the host didn't properly respond after a specified time (TCP error code 10060).
  • An established connection failed because connected host has failed to respond.
  • There was an error processing the message or the timeout is exceeded by the remote host.
  • Underlying network resource issue.

Resolution

The SocketException errors indicate that the VM hosting the applications is unable to convert the name <mynamespace>.servicebus.windows.net to the corresponding IP address.

Check to see if the following command succeeds in mapping to an IP address.

PS C:\> nslookup <mynamespace>.servicebus.windows.net

Which should provide an output like:

Name:    <cloudappinstance>.cloudapp.net
Address:  XX.XX.XXX.240
Aliases:  <mynamespace>.servicebus.windows.net

If the above name does not resolve to an IP and the namespace alias, check with the network administrator to investigate further. Name resolution is done through a DNS server typically a resource in the customer network. If the DNS resolution is done by Azure DNS, contact Azure support.

If name resolution works as expected, check if connections to Azure Service Bus is allowed here.

MessagingException

Cause

MessagingException is a generic exception that might be thrown for various reasons. Some of the reasons are:

  • An attempt is made to create a QueueClient on a Topic or a Subscription.
  • The size of the message sent is greater than the limit for the given tier. Read more about the Service Bus quotas and limits.
  • Specific data plane request (send, receive, complete, abandon) was terminated due to throttling.
  • Transient issues caused due to service upgrades and restarts.

Note

The above list of exceptions is not exhaustive.

Resolution

The resolution steps depend on what caused the MessagingException to be thrown.

  • For transient issues (where isTransient is set to true) or for throttling issues, retrying the operation might resolve it. The default retry policy on the SDK can be used for this.
  • For other issues, the details in the exception indicate the issue and resolution steps can be deduced from the same.

StorageQuotaExceededException

Cause

The StorageQuotaExceededException is generated when the total size of entities in a premium namespace exceeds the limit of 1 TB per messaging unit.

Resolution

  • Increase the number of messaging units assigned to the premium namespace
  • If you're already using maximum allowed messaging units for a namespace, create a separate namespace.

Next steps

For the complete Service Bus .NET API reference, see the Azure .NET API reference. For troubleshooting tips, see the Troubleshooting guide.