You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -76,38 +77,40 @@ ServiceBusErrors often have an underlying AMQP error code which specifies whethe
76
77
*`retry_mode`: The delay behavior between retry attempts. Supported values are 'fixed' or 'exponential'
77
78
When an exception is surfaced to the application, either all retries were applied unsuccessfully, or the exception was considered non-transient.
78
79
79
-
#### Connection and Authentication Exceptions
80
-
81
-
-**ServiceBusConnectionError:** An error occurred in the connection to the se
82
-
rvice. This may have been caused by a transient network issue or service proble
83
-
m. It is recommended to retry.
80
+
#### Authentication Exceptions
84
81
85
82
-**ServiceBusAuthenticationError:** An error occurred when authenticating the connection to the service. This may have been caused by the credentials being incorrect. It is recommended to check the credentials.
86
83
87
84
-**ServiceBusAuthorizationError:** An error occurred when authorizing the connection to the service. This may have been caused by the credentials not having the right permission to perform the operation. It is recommended to check the permission of the credentials.
88
85
89
-
#### Operation and Timeout Exceptions
86
+
See the [Troubleshooting Authentication issues](#troubleshooting-authentication-issues) section to troubleshoot authentication/permission issues.
87
+
88
+
#### Connection and Timeout Exceptions
89
+
90
+
-**ServiceBusConnectionError:** An error occurred in the connection to the service. This may have been caused by a transient network issue or service problem. It is recommended to retry.
90
91
91
92
-**OperationTimeoutError:** This indicates that the service did not respond to an operation within the expected amount of time. This may have been caused by a transient network issue or service problem. The service may or may not have successfully completed the request; the status is not known. It is recommended to attempt to verify the current state and retry if necessary.
92
93
93
94
-**ServiceBusCommunicationError:** 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. For details on which ports need to be open, see the [Azure Service Bus FAQ: What ports do I need to open on the firewall?](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-faq#what-ports-do-i-need-to-open-on-the-firewall--).
94
95
95
-
#### Message Handling Exceptions
96
+
See the [Troubleshooting Connectivity issues](#troubleshooting-connectivity-issues) section to troubleshoot connection and timeout issues. More information on AMQP errors in Azure Service Bus can be found [here](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-amqp-troubleshoot).
97
+
98
+
#### Message and Session Handling Exceptions
96
99
97
100
-**MessageSizeExceededError:** This indicates that the max message size has been exceeded. The message size includes the body of the message, as well as any associated metadata and system overhead. The best approach for resolving this error is to reduce the number of messages being sent in a batch or the size of the body included in the message. Because size limits are subject to change, please refer to [Service Bus quotas](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-quotas) for specifics.
98
101
99
102
-**MessageAlreadySettled:** This indicates failure to settle the message. This could happen when trying to settle an already-settled message.
100
103
101
-
-**MessageLockLostError:** Indicates that the lock on the message is lost. Callers should attempt to receive and process the message again. This exception only applies to entities that don't use sessions. This error occurs if processing takes longer than the lock duration and the message lock isn't renewed. This error can also occur when the link is detached due to a transient network issue or when the link is idle for 10 minutes, as enforced by the service. `AutoLockRenewer` could help on keeping the lock of the message automatically renewed.
102
-
103
104
-**MessageNotFoundError:** This occurs when attempting to receive a deferred message by sequence number for a message that either doesn't exist in the entity, or is currently locked.
104
105
105
-
#### Session Handling Exceptions
106
+
-**MessageLockLostError:** Indicates that the lock on the message is lost. Callers should attempt to receive and process the message again. This exception only applies to entities that don't use sessions. This error occurs if processing takes longer than the lock duration and the message lock isn't renewed. This error can also occur when the link is detached due to a transient network issue or when the link is idle for 10 minutes, as enforced by the service. `AutoLockRenewer` could help on keeping the lock of the message automatically renewed.
106
107
107
108
-**SessionLockLostError:** The lock on the session has expired. All unsettled messages that have been received can no longer be settled. It is recommended to reconnect to the session if receive messages again if necessary. You should be aware of the lock duration of a session and keep renewing the lock before expiration in case of long processing time. `AutoLockRenewer` could help on keeping the lock of the session automatically renewed.
108
109
109
110
-**SessionCannotBeLockedError:** Attempt to connect to 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.
110
111
112
+
See the [Troubleshooting message handling issues](#troubleshooting-message-handling-issues) section to troubleshoot message and session lock issues.
113
+
111
114
#### Service and Entity Exceptions
112
115
113
116
-**ServiceBusQuotaExceededError:** This typically indicates that there are too many active receive operations for a single entity. In order to avoid this error, reduce the number of potential concurrent receives. You can use batch receives to attempt to receive multiple messages per receive request. Please see [Service Bus quotas](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-quotas) for more information.
@@ -124,6 +127,8 @@ m. It is recommended to retry.
124
127
125
128
-**AutoLockRenewTimeout:** The time allocated to renew the message or session lock has elapsed. You could re-register the object that wants be auto lock renewed or extend the timeout in advance.
126
129
130
+
See the [Troubleshooting message handling issues](#troubleshooting-message-handling-issues) to help troubleshoot AutoLockRenewer errors.
131
+
127
132
## Threading and concurrency issues
128
133
129
134
### Thread safety limitations
@@ -199,7 +204,7 @@ with client:
199
204
executor.submit(send_batch, i, sender)
200
205
```
201
206
202
-
## Authentication issues
207
+
## Troubleshooting Authentication issues
203
208
204
209
Authentication errors typically occur when the credentials provided are incorrect or have expired. Authorization errors occur when the authenticated identity doesn't have sufficient permissions.
205
210
@@ -211,7 +216,7 @@ The following verification steps are recommended, depending on the type of autho
211
216
212
217
-[Verify the correct RBAC roles were granted](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-managed-service-identity) - Indicated by errors: `Send/Listen claim(s) are required to perform this operation.` In this case, ensure that the appropriate roles were assigned: `Azure Service Bus Data Owner`, `Azure Service Bus Data Sender`, or `Azure Service Bus Data Receiver`.
213
218
214
-
## Connectivity issues
219
+
## Troubleshooting Connectivity issues
215
220
216
221
### Timeout when connecting to service
217
222
@@ -251,11 +256,11 @@ For more information about the `azure-identity` library, see: [Azure Identity cl
251
256
252
257
## Troubleshooting message handling issues
253
258
254
-
### Message lock issues
259
+
### Message and session lock issues
255
260
256
-
Messages in Service Bus have a lock duration during which they must be settled (completed, abandoned, etc.).
261
+
Messages, sessionful and non-sessionful, in Service Bus have a lock duration during which they must be settled (completed, abandoned, etc.).
257
262
258
-
**MessageLockLostError resolution:**
263
+
**MessageLockLostError and SessionLockLostError resolution:**
259
264
1. Process messages faster or increase lock duration
260
265
2. If setting `prefetch_count` to a large number, consider setting it lower as it can cause message lock expiration if processing takes too long. The client cannot extend locks for prefetched messages.
261
266
3. Use `AutoLockRenewer` for long-running processing.
@@ -273,8 +278,6 @@ with receiver:
273
278
receiver.complete_message(message)
274
279
```
275
280
276
-
3. Handle lock lost errors gracefully by catching the exception and potentially re-receiving the message
Mixing synchronous and asynchronous Service Bus operations can cause issues such as async operations hanging indefinitely due to the event loop being blocked. Ensure that blocking calls are not made when receiving and message processing.
363
-
365
+
Mixing synchronous and asynchronous Service Bus operations can cause issues such as async operations, such as the `AutoLockRenewer`, hanging indefinitely due to the event loop being blocked. Ensure that blocking calls are not made when receiving and message processing.
0 commit comments