服务总线消息传送异常Service Bus messaging exceptions

本文列出了 .NET Framework API 生成的 .NET 异常。This article lists the .NET exceptions generated by .NET Framework APIs.

异常类别Exception categories

消息传送 API 会生成以下类别的异常,以及在尝试修复这些异常时可以采取的相关操作。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. 用户代码错误(System.ArgumentExceptionSystem.InvalidOperationExceptionSystem.OperationCanceledExceptionSystem.Runtime.Serialization.SerializationException)。User coding error (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). 常规操作:继续之前尝试修复代码。General action: try to fix the code before proceeding.
  2. 设置/配置错误(Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundExceptionSystem.UnauthorizedAccessException)。Setup/configuration error (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. 常规操作:检查配置,必要时进行更改。General action: review your configuration and change if necessary.
  3. 暂时性异常(Microsoft.ServiceBus.Messaging.MessagingExceptionMicrosoft.ServiceBus.Messaging.ServerBusyExceptionMicrosoft.ServiceBus.Messaging.MessagingCommunicationException)。Transient exceptions (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). 常规操作:重试操作或通知用户。General action: retry the operation or notify users. 客户端 SDK 中的 RetryPolicy 类可以配置为自动处理重试。The RetryPolicy class in the client SDK can be configured to handle retries automatically. 有关详细信息,请参阅重试指南For more information, see Retry guidance.
  4. 其他异常(System.Transactions.TransactionExceptionSystem.TimeoutExceptionMicrosoft.ServiceBus.Messaging.MessageLockLostExceptionMicrosoft.ServiceBus.Messaging.SessionLockLostException)。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
TimeoutExceptionTimeoutException 服务器在 OperationTimeout 控制的指定时间内未响应请求的操作。The server didn't respond to the requested operation within the specified time, which is controlled by OperationTimeout. 服务器可能已完成请求的操作。The server may 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.
InvalidOperationExceptionInvalidOperationException 不允许在服务器或服务中执行请求的用户操作。The requested user operation isn't allowed within the server or service. 有关详细信息,请查看异常消息。See the exception message for details. 例如,如果在 ReceiveAndDelete 模式下收到消息,则 Complete() 将生成此异常。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.
OperationCanceledExceptionOperationCanceledException 尝试对已关闭、中止或释放的对象调用某个操作。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.
UnauthorizedAccessExceptionUnauthorizedAccessException TokenProvider 对象无法获取令牌,该令牌无效,或者令牌不包含执行操作所需的声明。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.
提供给该方法的一个或多个参数均无效。One or more arguments supplied to the method are invalid.
提供给 NamespaceManagerCreate 的 URI 包含路径段。The URI supplied to NamespaceManager or Create contains path segment(s).
提供给 NamespaceManagerCreate 的 URI 方案无效。The URI scheme supplied to NamespaceManager or Create is invalid.
属性值大于 32 KB。The property value is larger than 32 KB.
检查调用代码并确保参数正确。Check the calling code and make sure the arguments are correct. 重试不起作用。Retry doesn't help.
MessagingEntityNotFoundExceptionMessagingEntityNotFoundException 与操作关联的实体不存在或已被删除。Entity associated with the operation doesn't exist or it has been deleted. 确保该实体存在。Make sure the entity exists. 重试不起作用。Retry doesn't help.
MessageNotFoundExceptionMessageNotFoundException 尝试接收具有特定序列号的消息。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.
MessagingCommunicationExceptionMessagingCommunicationException 客户端无法与服务总线建立连接。Client isn't able to establish a connection to Service Bus. 确保提供的主机名正确并且主机可访问。Make sure the supplied host name is correct and the host is reachable.

如果你的代码在使用防火墙/代理的环境中运行,请确保到服务总线域/IP 地址和端口的流量未被阻止。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.
ServerBusyExceptionServerBusyException 服务目前无法处理请求。Service isn't 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.
MessagingExceptionMessagingException 在以下情况下,可能会引发一般消息异常:Generic messaging exception that may be thrown in the following cases:

尝试使用属于其他实体类型(例如主题)的名称或路径创建 QueueClientAn attempt is made to create a QueueClient using a name or path that belongs to a different entity type (for example, a topic).

尝试发送大于 256 KB 的消息。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. 错误代码:50001、50002、50008。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.

检查 IsTransient 属性。Check the IsTransient property. 如果为 true,可以重试操作。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.
MessagingEntityAlreadyExistsExceptionMessagingEntityAlreadyExistsException 尝试使用已被该服务命名空间中另一实体使用的名称创建实体。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.
QuotaExceededExceptionQuotaExceededException 消息实体已达到其允许的最大大小,或已超出到命名空间的最大连接数。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. 请参阅QuotaExceededExceptionSee QuotaExceededException. 如果同时已删除消息,则重试可能会有帮助。Retry might help if messages have been removed in the meantime.
RuleActionExceptionRuleActionException 如果尝试创建无效的规则操作,服务总线将返回此异常。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.
FilterExceptionFilterException 如果尝试创建无效的筛选器,服务总线将返回此异常。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.
SessionCannotBeLockedExceptionSessionCannotBeLockedException 尝试接受具有特定会话 ID 的会话,但该会话当前已被另一客户端锁定。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.
TransactionSizeExceededExceptionTransactionSizeExceededException 事务包含过多的操作。Too many operations are part of the transaction. 减少此事务中操作的数目。Reduce the number of operations that are part of this transaction. 重试不起作用。Retry doesn't help.
MessagingEntityDisabledExceptionMessagingEntityDisabledException 对已禁用的实体请求运行时操作。Request for a runtime operation on a disabled entity. 激活实体。Activate the entity. 如果在此期间该实体已激活,则重试可能会有帮助。Retry might help if the entity has been activated in the interim.
NoMatchingSubscriptionExceptionNoMatchingSubscriptionException 如果向已启用预筛选的主题发送消息并且所有筛选器都不匹配,则服务总线返回此异常。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 doesn't help.
MessageSizeExceededExceptionMessageSizeExceededException 消息有效负载超出 256 KB 限制。A message payload exceeds the 256-KB limit. 256-KB 限制是指总消息大小,可能包括系统属性和任何 .NET 开销。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.
TransactionExceptionTransactionException 环境事务 (Transaction.Current) 无效。The ambient transaction (Transaction.Current) is invalid. 该事务可能已完成或已中止。It may have been completed or aborted. 内部异常可能提供了更多信息。Inner exception may provide additional information. 重试不起作用。Retry doesn't help.
TransactionInDoubtExceptionTransactionInDoubtException 已对未决事务尝试进行操作,或尝试提交该事务并且事务进入不确定状态。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, it's often the size of the queue. 错误消息属性会包含更多详细信息,如以下示例所示:The error message property contains further details, as in the following example:

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

该消息指出,主题超过其大小限制,本例中为 1 GB(默认大小限制)。The message states that the topic exceeded its size limit, in this case 1 GB (the default size limit).


对于命名空间,QuotaExceededException 可指示应用程序已超出到命名空间的最大连接数。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 ---> 
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. 如果读取器发生异常,以致无法调用 BrokeredMessage.Complete,就会出现这种情况。It can happen if the reader encounters an exception that prevents it from calling BrokeredMessage.Complete. 消息读取 10 次后,默认移至死信队列。After a message has been read 10 times, it moves to the dead-letter queue by default. 此行为由 QueueDescription.MaxDeliveryCount 属性控制,默认值为 10。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. 可以使用 FormatDeadLetterPath 方法帮助格式化死信队列路径。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. 识别这种情况的方法是查看 QueueDescription.MessageCountDetails 属性,它会显示消息的完整细目。The way to identify this is to look at the QueueDescription.MessageCountDetails property, which shows the full breakdown of the messages. 如果 ActiveMessageCount 属性很高或不断增加,则表示消息写入的速度超过读取的速度。If the ActiveMessageCount property is high or growing, then the messages aren't 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.

应检查 ServicePointManager.DefaultConnectionLimit 属性的值,因为达到此限制也会导致 TimeoutException 异常。You should check the value of the ServicePointManager.DefaultConnectionLimit property, as hitting this limit can also cause a TimeoutException.

预计会在维护操作(例如,服务总线服务更新或运行服务的资源上的 OS 更新)期间或操作间隙发生超时。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. 在 OS 更新期间,实体会四处移动,节点会更新或重启,这可能会导致超时。During OS updates, entities are moved around and nodes are updated or rebooted, which can cause timeouts. 有关 Azure 服务总线服务的服务级别协议 (SLA) 详细信息,请参阅服务总线的 SLAFor service level agreement (SLA) details for the Azure Service Bus service, see SLA for Service Bus.

队列和主题Queues and topics

对于队列和主题,超时在 MessagingFactorySettings.OperationTimeout 属性中作为连接字符串的一部分指定,或通过 ServiceBusConnectionStringBuilder 指定。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.



当使用 PeekLock 接收模式接收到消息并且客户端持有的消息锁在服务端过期时,将引发 MessageLockLostException。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 may 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.


发生 MessageLockLostException 时,客户端应用程序无法再处理该消息。In the event of a MessageLockLostException, the client application can no longer process the message. 客户端应用程序可以选择记录异常以进行分析,但客户端必须释放消息才行。The client application may optionally consider logging the exception for analysis, but the client must dispose off the message.

由于消息的锁已过期,它将返回队列(或订阅),并可由调用 receive 的下一个客户端应用程序处理。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 which calls receive.

如果超过了 MaxDeliveryCount,邮件可能会移至 DeadLetterQueue 。If the MaxDeliveryCount has exceeded then the message may be moved to the DeadLetterQueue.



如果接受了某个会话,且客户端持有的锁在服务端过期,将引发 SessionLockLostException。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 may 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.


发生 SessionLockLostException 时,客户端应用程序无法再处理会话上的消息。In the event of a SessionLockLostException, the client application can no longer process the messages on the session. 客户端应用程序可以考虑记录异常以进行分析,但客户端必须释放消息才行。The client application may 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 which 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 -A SocketException is thrown in the below cases -

  • 当由于主机在指定时间后没有正确响应而导致连接尝试失败时(TCP 错误代码 10060)。When a connection attempt fails because the host did not 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.


SocketException 错误表明承载应用程序的 VM 无法将名称 <mynamespace>.servicebus.chinacloudapi.cn 转换为相应的 IP 地址。The SocketException errors indicate that the VM hosting the applications is unable to convert the name <mynamespace>.servicebus.chinacloudapi.cn to the corresponding IP address.

检查以下命令是否成功映射到 IP 地址。Check to see if below command succeeds in mapping to an IP address.

PS C:\> nslookup <mynamespace>.servicebus.chinacloudapi.cn

它应该提供如下输出which should provide an output as below

Name:    <cloudappinstance>.chinacloudapp.cn
Address:  XX.XX.XXX.240
Aliases:  <mynamespace>.servicebus.chinacloudapi.cn

如果上述名称未解析为 IP 和命名空间别名,请检查确定网络管理员要进一步研究的名称。If the above name does not resolve to an IP and the namespace alias, check which the network administrator to investigate further. 名称解析是通过 DNS 服务器完成的,通常是客户网络中的资源。Name resolution is done through a DNS server typically a resource in the customer network. 如果 DNS 解析由 Azure DNS 完成,请与 Azure 支持部门联系。If the DNS resolution is done by Azure DNS please contact Azure support.

如果名称解析“按预期工作”,请在此处检查是否允许连接到 Azure 服务总线If name resolution works as expected, check if connections to Azure Service Bus is allowed here



MessagingException 是可能出于各种原因引发的一般异常。MessagingException is a generic exception that may be thrown for various reasons. 下面列出了其中的一些原因。Some of the reasons are listed below.

  • 尝试在“主题”或“订阅”上创建“QueueClient” 。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.


上述异常列表非完整列表。The above list of exceptions is not exhaustive.


解决方法步骤取决于引发 MessagingException 的原因。The resolution steps depend on what caused the MessagingException to be thrown.

  • 对于暂时性问题(其中 isTransient 设置为 true)或限制性问题,重试操作可能会解决该问题 。For transient issues (where *isTransient_ is set to true) or for _* throttling issues**, retrying the operation may resolve it. 可以为此利用 SDK 上的默认重试策略。The default retry policy on the SDK can be leveraged for this.
  • 对于其他问题,异常中的详细信息表明可以从相同地方推断问题和解决步骤。For other issues, the details in the exception indicate the issue and resolution steps can be deduced from the same.

后续步骤Next steps

有关服务总线 .NET API 的完整参考,请参阅 Azure .NET API 参考For the complete Service Bus .NET API reference, see the Azure .NET API reference. 有关故障排除提示信息,请参阅故障排除指南For troubleshooting tips, see the Troubleshooting guide