Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Azure Relay exceptions and how to resolve them | Microsoft Docs description: List of Azure Relay exceptions and suggested actions you can take to help resolve them. ms.topic: article ms.date: 01/24/2026 --- # Azure Relay exceptions This article lists some exceptions that might be generated by the Azure Relay APIs. This reference is subject to change, so check back for updates. ## Exception categories The Relay APIs generate exceptions that might fall into the following categories. Also listed are suggested actions that you can take to help resolve the exceptions. * **User coding error**: [System.ArgumentException](/dotnet/api/system.argumentexception), [System.InvalidOperationException](/dotnet/api/system.invalidoperationexception), [System.OperationCanceledException](/dotnet/api/system.operationcanceledexception), [System.Runtime.Serialization.SerializationException](/dotnet/api/system.runtime.serialization.serializationexception). **General action**: Try to fix the code before you proceed. * **Setup/configuration error**: [System.UnauthorizedAccessException](/dotnet/api/system.unauthorizedaccessexception). **General action**: Review your configuration. If necessary, change the configuration. * **Transient exceptions**: [Microsoft.ServiceBus.Messaging.MessagingException](/dotnet/api/microsoft.servicebus.messaging.messagingexception), [Microsoft.ServiceBus.Messaging.ServerBusyException](/dotnet/api/microsoft.servicebus.messaging.serverbusyexception), [Microsoft.ServiceBus.Messaging.MessagingCommunicationException](/dotnet/api/microsoft.servicebus.messaging.messagingcommunicationexception). **General action**: Retry the operation or notify users. * **Other exceptions**: [System.Transactions.TransactionException](/dotnet/api/system.transactions.transactionexception), [System.TimeoutException](/dotnet/api/system.timeoutexception). **General action**: Specific to the exception type. See the table in the following section. ## Exception types The following table lists messaging exception types and their causes. It also notes suggested actions you can take to help resolve the exceptions. | **Exception type** | **Description** | **Suggested action** | **Note on automatic or immediate retry** | | --- | --- | --- | --- | | [Timeout](/dotnet/api/system.timeoutexception) |The server didn't respond to the requested operation within the specified time, which is controlled by [OperationTimeout](/dotnet/api/microsoft.servicebus.messaging.messagingfactorysettings.operationtimeout). The server might have completed the requested operation. It can happen due to network or other infrastructure delays. |Check the system state for consistency, and then retry, if necessary. See [TimeoutException](#timeoutexception). |Retry might help in some cases; add retry logic to code. | | [Invalid Operation](/dotnet/api/system.invalidoperationexception) |The requested user operation isn't allowed within the server or service. See the exception message for details. |Check the code and the documentation. Make sure that the requested operation is valid. |Retry doesn't help. | | [Operation Canceled](/dotnet/api/system.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. | | [Unauthorized Access](/dotnet/api/system.unauthorizedaccessexception) |The [TokenProvider](/dotnet/api/microsoft.servicebus.tokenprovider) object couldn't acquire a token, the token is invalid, or the token doesn't contain the claims required to perform the operation. |Make sure that 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. | | [Argument Exception](/dotnet/api/system.argumentexception),<br /> [Argument Null](/dotnet/api/system.argumentnullexception),<br />[Argument Out Of Range](/dotnet/api/system.argumentoutofrangeexception) |One or more of the following issues has occurred:<br />One or more arguments supplied to the method are invalid.<br /> The URI supplied to [NamespaceManager](/dotnet/api/microsoft.servicebus.namespacemanager) or [Create](/dotnet/api/microsoft.servicebus.messaging.messagingfactory.create) contains one or more path segments.<br />The URI scheme supplied to [NamespaceManager](/dotnet/api/microsoft.servicebus.namespacemanager) or [Create](/dotnet/api/microsoft.servicebus.messaging.messagingfactory.create) is invalid. <br />The property value is larger than 32 KB. |Check the calling code and make sure the arguments are correct. |Retry doesn't help. | | [Server Busy](/dotnet/api/microsoft.servicebus.messaging.serverbusyexception) |Service isn't able to process the request at this time. |The client can wait for a period of time, then retry the operation. |The client might retry after a specific interval. If a retry results in a different exception, check the retry behavior of that exception. | | [Quota Exceeded](/dotnet/api/microsoft.servicebus.messaging.quotaexceededexception) |The messaging entity has reached its maximum allowable size. |Create space in the entity by receiving messages from the entity or its subqueues. See [QuotaExceededException](#quotaexceededexception). |Retry might help if messages have been removed in the meantime. | | [Message Size Exceeded](/dotnet/api/microsoft.servicebus.messaging.messagesizeexceededexception) |A message payload exceeds the 256-KB limit. The 256-KB limit is the total message size. The total message size can include system properties and any Microsoft .NET overhead. |Reduce the size of the message payload, then retry the operation. |Retry doesn't help. | ## QuotaExceededException [QuotaExceededException](/dotnet/api/microsoft.servicebus.messaging.quotaexceededexception) indicates that a quota for a specific entity has been exceeded. For Relay, this exception wraps the [System.ServiceModel.QuotaExceededException](/dotnet/api/system.servicemodel.quotaexceededexception), which indicates that the maximum number of listeners has been exceeded for this endpoint. It's indicated in the **MaximumListenersPerEndpoint** value of the exception message. ## TimeoutException A [TimeoutException](/dotnet/api/system.timeoutexception) indicates that a user-initiated operation is taking longer than the operation timeout. Check the value of the [ServicePointManager.DefaultConnectionLimit](/dotnet/api/system.net.servicepointmanager.defaultconnectionlimit#System_Net_ServicePointManager_DefaultConnectionLimit) property. Reaching this limit also can cause a [TimeoutException](/dotnet/api/system.timeoutexception). For Relay, you might receive timeout exceptions when you first open a relay sender connection. There are two common causes for this exception: * The [OpenTimeout](/previous-versions/) value might be too small (if even by a fraction of a second). * An on-premises relay listener might be unresponsive (or it might encounter firewall rules issues that prohibit listeners from accepting new client connections), and the [OpenTimeout](/previous-versions/) value is less than about 20 seconds. Example: ``` '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. ``` ### Common causes There are two common causes for this 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 whether the value in your code is set to something too small. CPU usage and the condition of the network can affect the time it takes for an operation to complete. It's a good idea not to set the operation timeout to a very small value. * **Transient service error** Occasionally, the Relay service might experience delays in processing requests. It might happen, for example, during periods of high traffic. If it occurs, retry your operation after a delay, until the operation is successful. If the same operation continues to fail after multiple attempts, check the [Azure service status site](https://azure.microsoft.com/status/) to see if there are known service outages. ## ConnectionLostException - NameRenewalFailed ### Symptoms Your client receives the exception: `Microsoft.Azure.Relay.ConnectionLostException : InternalServerError: NameRenewalFailed`. ### Cause Azure Relay service restarts listener connections every 24 hours. This behavior is by design. The Azure Relay service disconnects a listener active connection every 24 hours, and the listener will reconnect with the server using the retry mechanism. ### Resolution No action on your part as the listener automatically reconnects to the server. If you notice that your listener isn't connecting again, [submit a ticket](https://azure.microsoft.com/support/options/) to the support team. ## Next steps * [Azure Relay FAQs](relay-faq.yml) * [Create a relay namespace](relay-create-namespace-portal.md) * [Get started with Azure Relay and .NET](relay-hybrid-connections-dotnet-get-started.md) * [Get started with Azure Relay and Node](relay-hybrid-connections-node-get-started.md)