Troubleshooting guide for Azure Service Bus

This article provides troubleshooting tips and recommendations for a few issues that you see when using Azure Service Bus.

Check service health before troubleshooting your client

Start by confirming whether Azure Service Bus is healthy in your region. This quick check tells you where to focus your troubleshooting. Begin with these two checks:

1. Check Azure Service Health. In the Azure portal, open Azure Service Health, or go to the Azure status page, to see whether Service Bus has an active health event or advisory in your region. Service Health reports service-side events that affect a targeted set of customers, such as a subset of customers in a region.
2. Check Resource Health for your namespace. In the Azure portal, open your Service Bus namespace and select Resource health. Resource Health shows the current and recent health of your specific namespace. For more information, see Azure Resource Health overview.

If either check shows an active service-side event, the service is the likely source. The Service Bus SDK's built-in retry policy automatically retries transient failures and reconnects after brief interruptions. A longer outage can exceed the built-in retry limits, so make sure your application also retries or resumes processing once the service recovers. If both checks show the service is healthy, continue with the client-side troubleshooting in the rest of this article.

Resource health

The unhealthy period marked on the Resource health page of your Service Bus namespace in the Azure portal might be longer by a few minutes than the actual period. For example, the page might indicate that the namespace is unhealthy for 5-6 minutes, while the actual unhealthy period was only 1-2 minutes.

This behavior is due to the alert system's evaluation mechanism, which uses a 3-minute evaluation interval combined with a 5-minute lookback window. The lookback window is used to ensure that there are no errors for at least 5 minutes before considering the namespace healthy. In the above example, the namespace got healthy in a minute or two but the next evaluation happened was at least 5 minutes (lookback window) after the namespace became healthy.

Connectivity issues

Time out when connecting to service

Depending on the host environment and network, a connectivity issue might present to applications as either a TimeoutException, OperationCanceledException, or a ServiceBusException with Reason of ServiceTimeout and most often occurs when the client can't find a network path to the service.

To troubleshoot:

• Verify that the connection string or fully qualified domain name that you specified when creating the client is correct. For information on how to acquire a connection string, see Get a Service Bus connection string.
• If your namespace uses a private endpoint with public access disabled, confirm from a host inside the virtual network that the namespace resolves to the private IP address. For details, see Troubleshoot private endpoint connectivity.
• Check the firewall and port permissions in your hosting environment. Check that the Advanced Message Queuing Protocol (AMQP) ports 5671 and 5672 are open and that the endpoint is allowed through the firewall.
• Try using the Web Socket transport option, which connects using port 443. For details, see configure the transport.
• See if your network is blocking specific IP addresses. For details, see What IP addresses do I need to allow?
• If applicable, verify the proxy configuration. For details, see: Configuring the transport
• For more information about troubleshooting network connectivity, see: Connectivity, certificate, or timeout issues.

Send or receive operation times out

Most send and receive timeouts are transient and resolve on their own. Some timeouts point to conditions on the service side that you should check. This section helps you distinguish between these two types of timeouts and choose the right response.

Transient timeouts resolve automatically

A transient timeout is a brief interruption, such as a momentary network blip, a link that's being reestablished, or a short-lived spike in load. The client libraries automatically retry transient failures, including timeouts, by using the built-in retry policy. The default policy retries up to three times with exponential back-off and a per-attempt timeout (TryTimeout) of 60 seconds, so most transient timeouts clear on their own with no action from you.

To let the SDK handle this work:

• Keep the default retry policy. It gives the SDK room to recover transient failures for you. Lowering the maximum retry count or TryTimeout reduces that room, so keep the defaults unless you have a specific reason to change them.
• A ServiceBusException with a Reason of ServiceTimeout (or the equivalent transient error in your SDK) is safe to retry, so let the SDK retry it or retry the operation yourself.
• A single timeout that succeeds on the next call can be expected and needs no action.

When to check the service side

If timeouts continue across retries and client restarts rather than clearing on their own, check the health of the service. Look for two patterns:

• An unresponsive entity. A single queue, topic, or subscription stops responding while the rest of the namespace continues to work. Send and receive operations against that one entity time out even though connectivity to the namespace is healthy.
• A rise in internal server errors. Requests across the namespace begin returning internal server errors, such as a ServiceBusException with a Reason of ServiceCommunicationProblem, or an AMQP amqp:internal-error. A sustained rise, as opposed to the occasional retryable error, points to a service-side condition.

To confirm and get help:

• Open the Resource health page for your namespace in the Azure portal to check the health that the service reports. For more information, see Resource health.
• In the Azure portal, watch the Server Errors metric. A sustained rise in server errors points to the service side rather than your client. For the metric definitions, see Monitoring Azure Service Bus data reference.
• If you also see a rise in the Throttled Requests metric, the namespace is reaching its throughput or resource limits. That's a capacity condition rather than a service fault, so address it by reducing load or scaling up, such as by adding messaging units on the Premium tier. For more information, see Throttling in Azure Service Bus.
• Confirm the client isn't the cause by working through Connectivity, certificate, or timeout issues.
• If Resource health reports a problem, the platform detects it and works to mitigate it. The SDK automatically reconnects through brief interruptions, but a longer service-side event can exceed the retry limits, so have your application retry or resume processing once the service recovers. Monitor Resource health until it does.
• If Resource health shows the namespace as healthy but you still see a single unresponsive entity or a sustained rise in server errors, open a support request so the team can investigate the service side.

Set how long a receive waits

How long a receive call waits for a message before it returns depends on the SDK. If a receive waits longer than you expect, it's usually because no wait limit is set rather than a problem with the service.

• In the .NET, Java, and JavaScript libraries, a receive is bounded by default. The maximum wait time defaults to 60 seconds, after which the call returns an empty result if no message arrived.

• In the Python library, max_wait_time defaults to None, so the call waits until a message arrives or the connection is closed. Set a max_wait_time value to bound it.

• In the Go library, ReceiveMessages takes its timeout from the context.Context that you pass in, and it waits until at least one message arrives or the context is canceled. Pass a context with a deadline to set how long a receive waits:

  ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
  defer cancel()
  messages, err := receiver.ReceiveMessages(ctx, 10, nil)
  

In Go and Python, setting a context deadline (Go) or a max_wait_time value (Python) gives you predictable receive behavior.

Secure socket layer (SSL) handshake failures

This error can occur when an intercepting proxy is used. To verify, We recommend that you test the application in the host environment with the proxy disabled.

Socket exhaustion errors

Applications should prefer treating the Service Bus types as singletons, creating and using a single instance through the lifetime of the application. Each new ServiceBusClient created results in a new AMQP connection, which uses a socket. The ServiceBusClient type manages the connection for all types created from that instance. Each ServiceBusReceiver, ServiceBusSessionReceiver, ServiceBusSender, and ServiceBusProcessor manages its own AMQP link for the associated Service Bus entity. When you use ServiceBusSessionProcessor, multiple AMQP links are established depending on the number of sessions that are being processed concurrently.

The clients are safe to cache when idle; they ensure efficient management of network, CPU, and memory use, minimizing their impact during periods of inactivity. It's also important that either CloseAsync or DisposeAsync is called when a client is no longer needed to ensure that network resources are properly cleaned up.

Adding components to the connection string doesn't work

The current generation of the Service Bus client library supports connection strings only in the form published by the Azure portal. The connection strings are intended to provide basic location and shared key information only. Configuring behavior of the clients is done through its options.

Previous generations of the Service Bus clients allowed for some behavior to be configured by adding key/value components to a connection string. These components are no longer recognized and have no effect on client behavior.

"TransportType=AmqpWebSockets" alternative

To configure Web Sockets as the transport type, see Configuring the transport.

"Authentication=Managed Identity" Alternative

To authenticate with Managed Identity, see: Identity and Shared Access Credentials. For more information about the Azure.Identity library, see Authentication and the Azure SDK.

Managed identity authentication failures

When your application authenticates with a managed identity instead of a connection string, connection attempts can fail with an authorization error even when the network path to the service is healthy. Depending on the SDK, the failure surfaces as an Unauthorized error, a ServiceBusException with an authorization-related reason, or a "Put token failed" error.

These failures come from token acquisition or role assignment in your host environment, not from the Service Bus client. The same causes apply to every Service Bus SDK (.NET, Java, JavaScript, Python, and Go), because each one acquires Microsoft Entra tokens through the Azure Identity library.

To troubleshoot this problem:

• Confirm that the identity has an Azure role assignment on the namespace, queue, or topic. Sending requires the Azure Service Bus Data Sender role and receiving requires the Azure Service Bus Data Receiver role. For steps, see Authenticate a managed identity with Microsoft Entra ID to access Azure Service Bus resources.
• Confirm that the client requests the token scope https://servicebus.azure.net/.default. The issued token's aud (audience) claim is then https://servicebus.azure.net. The role assignment is a separate requirement from the scope, so verify it as well.
• Verify that DefaultAzureCredential selects the intended credential. When multiple credentials are available in the host, DefaultAzureCredential uses the first one in its resolution order. Enable Azure Identity logging or specify the credential explicitly to confirm which identity is used. For the .NET credential resolution order and more troubleshooting steps, see DefaultAzureCredential and Troubleshoot Azure Identity authentication issues. The Azure Identity library for each language follows the same credential chain.
• Allow time for a new role assignment to propagate, which can take several minutes.
• Check that the host clock is accurate and synchronized. Microsoft Entra ID validates tokens against their issue and expiry times.

Azure Kubernetes Service (AKS) workload identity

When you run on AKS with workload identity, the preceding checks still apply. Also verify the workload identity configuration:

• The Kubernetes service account is annotated with the identity's client ID.
• The pod has the azure.workload.identity/use label.
• A federated identity credential links the managed identity or Microsoft Entra application to the cluster's OpenID Connect (OIDC) issuer.

To assign a managed identity to an AKS cluster, see the Azure Kubernetes Service tab in Migrate an application to use passwordless connections.

Logging and diagnostics

The Service Bus client library is fully instrumented for logging information at various levels of detail using the .NET EventSource to emit information. Logging is performed for each operation and follows the pattern of marking the starting point of the operation, its completion, and any exceptions encountered. Additional information that might offer insight is also logged in the context of the associated operation.

Enable logging

The Service Bus client logs are available to any EventListener by opting into the sources starting with Azure-Messaging-ServiceBus or by opting into all sources that have the trait AzureEventSource. To make capturing logs from the Azure client libraries easier, the Azure.Core library used by Service Bus offers an AzureEventSourceListener.

For more information, see: Logging with the Azure SDK for .NET.

Distributed tracing

The Service Bus client library supports distributed tracing through integration with the Application Insights SDK. It also has experimental support for the OpenTelemetry specification via the .NET ActivitySource type introduced in .NET 5. In order to enable ActivitySource support for use with OpenTelemetry, see ActivitySource support.

In order to use the GA DiagnosticActivity support, you can integrate with the Application Insights SDK. More details can be found in ApplicationInsights with Azure Monitor.

The library creates the following spans:

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

Most of the spans are self-explanatory and are started and stopped during the operation that bears its name. The span that ties the others together is Message. The way that the message is traced is via the Diagnostic-Id that is set in the ServiceBusMessage.ApplicationProperties property by the library during send and schedule operations. In Application Insights, Message spans are displayed as linking out to the various other spans that were used to interact with the message, for example, the ServiceBusReceiver.Receive span, the ServiceBusSender.Send span, and the ServiceBusReceiver.Complete span would all be linked from the Message span. Here's an example of what this looks like in Application Insights:

In the screenshot, you see the end-to-end transaction that can be viewed in Application Insights in the portal. In this scenario, the application is sending messages and using the ServiceBusSessionProcessor to process them. The Message activity is linked to ServiceBusSender.Send, ServiceBusReceiver.Receive, ServiceBusSessionProcessor.ProcessSessionMessage, and ServiceBusReceiver.Complete.

Troubleshoot sender issues

Can't send a batch with multiple partition keys

When an app sends a batch to a partition-enabled entity, all messages included in a single send operation must have the same PartitionKey. If your entity is session-enabled, the same requirement holds true for the SessionId property. In order to send messages with different PartitionKey or SessionId values, group the messages in separate ServiceBusMessageBatch instances or include them in separate calls to the SendMessagesAsync overload that takes a set of ServiceBusMessage instances.

Batch fails to send

A message batch is either ServiceBusMessageBatch containing two or more messages, or a call to SendMessagesAsync where two or more messages are passed in. The service doesn't allow a message batch to exceed 1 MB. This behavior is true whether or not the Premium large message support feature is enabled. If you intend to send a message greater than 1 MB, it must be sent individually rather than grouped with other messages. Unfortunately, the ServiceBusMessageBatch type doesn't currently support validating that a batch doesn't contain any messages greater than 1 MB as the size is constrained by the service and might change. So, if you intend to use the premium large message support feature, ensure that you send messages over 1 MB individually.

Troubleshoot receiver issues

Number of messages returned doesn't match number requested in batch receive

When attempting to do a batch receive operation, that is, passing a maxMessages value of two or greater to the ReceiveMessagesAsync method, you aren't guaranteed to receive the number of messages requested, even if the queue or subscription has that many messages available at that time, and even if the entire configured maxWaitTime hasn't yet elapsed. To maximize throughput and avoid lock expiration, once the first message comes over the wire, the receiver waits an extra 20 milliseconds for any extra messages before dispatching the messages for processing. The maxWaitTime controls how long the receiver waits to receive the first message - subsequent messages are waited for 20 milliseconds. Therefore, your application shouldn't assume that all messages available are received in one call.

Message or session lock is lost before lock expiration time

The Service Bus service uses the AMQP protocol, which is stateful. Due to the nature of the protocol, if the link that connects the client and the service is detached after a message is received, but before the message is settled, the message isn't able to be settled on reconnecting the link. Links can be detached due to a short-term transient network failure, a network outage, or due to the service enforced 10-minute idle timeout. The reconnection of the link happens automatically as a part of any operation that requires the link, that is, settling or receiving messages. In this situation, you receive a ServiceBusException with Reason of MessageLockLost or SessionLockLost even if the lock expiration time isn't yet passed. If a message is received repeatedly but never settled because of lock loss, its delivery count increases until the message is moved to the dead-letter queue. For more information, see Why did my message go to the dead-letter queue?.

How to browse scheduled or deferred messages

Scheduled and deferred messages are included when peeking messages. They're identified by the ServiceBusReceivedMessage.State property. Once you have the SequenceNumber of a deferred message, you can receive it with a lock via the ReceiveDeferredMessagesAsync method.

When working with topics, you can't peek scheduled messages on the subscription, as the messages remain in the topic until the scheduled enqueue time. As a workaround, you can construct a ServiceBusReceiver passing in the topic name in order to peek such messages. No other operations with the receiver work when using a topic name.

How to browse session messages across all sessions

You can use a regular ServiceBusReceiver to peek across all sessions. To peek for a specific session you can use the ServiceBusSessionReceiver, but you need to obtain a session lock.

NotSupportedException thrown when accessing message body

This issue occurs most often in interop scenarios when receiving a message sent from a different library that uses a different AMQP message body format. If you're interacting with these types of messages, see the AMQP message body sample to learn how to access the message body.

Server busy errors when many receivers are open

If you open a large number of receivers on the same queue, topic, or subscription and keep them active at the same time, you might see a ServiceBusException with a Reason of ServiceBusy. Service Bus allows up to 5,000 concurrent receive requests on a single entity, combined across all subscriptions of a topic. Each open receiver issues credit and continually polls for messages - even when the entity is empty - so a large number of idle receivers can push the combined receive requests past this limit, and additional requests are rejected.

The Service Bus SDKs automatically retry server busy responses using exponential backoff, so transient occurrences are handled for you. To avoid reaching the limit, keep the number of concurrent receivers on a single entity well below 5,000, close receivers you no longer need instead of leaving them idle, and scale out across multiple entities if you need a very large number of consumers. For more information, see Throttling operations on Azure Service Bus.

Troubleshoot processor issues

Autolock renewal isn't working

Autolock renewal relies on the system time to determine when to renew a lock for a message or session. If your system time isn't accurate, for example, your clock is slow, then lock renewal might not happen before the lock is lost. Ensure that your system time is accurate if autolock renewal isn't working.

Processor appears to hang or have latency issues when using high concurrency

Thread starvation usually causes this behavior, particularly when using the session processor and using a very high value for MaxConcurrentSessions, relative to the number of cores on the machine. The first thing to check would be to make sure you aren't doing sync-over-async in any of your event handlers. Sync-over-async is an easy way to cause deadlocks and thread starvation. Even if you aren't doing sync over async, any pure sync code in your handlers could contribute to thread starvation. If you determined that isn't the issue, for example, because you have pure async code, you can try increasing your TryTimeout. It relieves pressure on the thread pool by reducing the number of context switches and timeouts that occur when using the session processor in particular. The default value for TryTimeout is 60 seconds, but it can be set all the way up to 1 hour. We recommend testing with the TryTimeout set to 5 minutes as a starting point and iterate from there. If none of these suggestions work, you simply need to scale out to multiple hosts, reducing the concurrency in your application, but running the application on multiple hosts to achieve the desired overall concurrency.

Further reading:

• Debug thread pool starvation
• Diagnosing .NET Core thread pool starvation with PerfView (Why my service isn't saturating all cores or seems to stall)
• Diagnosing thread pool exhaustion Issues in .NET Core Apps (video)

Session processor takes too long to switch sessions

This setting can be configured using the SessionIdleTimeout, which tells the processor how long to wait to receive a message from a session, before giving up and moving to another one. It's useful if you have many sparsely populated sessions, where each session only has a few messages. If you expect that each session will have many messages that trickle in, setting it too low can be counter productive, as it results in unnecessary closing of the session.

Processor stops immediately

This behavior is often observed for demo or testing scenarios. StartProcessingAsync returns immediately after the processor started. Calling this method doesn't block and keep your application alive while the processor is running, so you need some other mechanism to do so. For demos or testing, it's sufficient to just add a Console.ReadKey() call after you start the processor. For production scenarios, you likely want to use some sort of framework integration like BackgroundService to provide convenient application lifecycle hooks that can be used for starting and disposing the processor.

Troubleshoot transactions

For general information about transactions in Service Bus, see the Overview of Service Bus transaction processing.

Supported operations

Not all operations are supported when using transactions. To see the list of supported transactions, see Operations within a transaction scope.

Timeout

A transaction times out after a period of time, so it's important that processing that occurs within a transaction scope adheres to this timeout.

Operations in a transaction aren't retried

This behavior is by design. Consider the following scenario - you're attempting to complete a message within a transaction, but there's some transient error that occurs, for example, ServiceBusException with a Reason of ServiceCommunicationProblem. Suppose the request does actually make it to the service. If the client were to retry, the service would see two complete requests. The first complete isn't finalized until the transaction is committed. The second complete isn't able to even be evaluated before the first complete finishes. The transaction on the client is waiting for the complete to finish. It creates a deadlock where the service is waiting for the client to complete the transaction, but the client is waiting for the service to acknowledge the second complete operation. The transaction will eventually time out after 2 minutes, but it's a bad user experience. For this reason, we don't retry operations within a transaction.

Transactions across entities aren't working

In order to perform transactions that involve multiple entities, you need to set the ServiceBusClientOptions.EnableCrossEntityTransactions property to true. For details, see the Transactions across entities sample.

Quotas

Information about Service Bus quotas can be found here.

Connectivity, certificate, or timeout issues

The following steps help you with troubleshooting connectivity/certificate/timeout issues for all services under *.servicebus.windows.net.

• If your namespace uses a private endpoint with public access disabled, confirm name resolution before you run the connectivity checks that follow. A port check can succeed against the public endpoint even in that configuration, so resolution to a public IP address from inside the virtual network points to a DNS problem. For details, see Troubleshoot private endpoint connectivity.

• Browse to or wget https://<yournamespace>.servicebus.windows.net/. It helps with checking whether you have IP filtering or virtual network or certificate chain issues, which are common when using Java SDK.

  An example of successful message:

  <feed xmlns="http://www.w3.org/2005/Atom"><title type="text">Publicly Listed Services</title><subtitle type="text">This is the list of publicly-listed services currently available.</subtitle><id>uuid:27fcd1e2-3a99-44b1-8f1e-3e92b52f0171;id=30</id><updated>2019-12-27T13:11:47Z</updated><generator>Service Bus 1.1</generator></feed>
  

  An example of failure error message:

  <Error>
      <Code>400</Code>
      <Detail>
          Bad Request. To know more visit https://aka.ms/sbResourceMgrExceptions. . TrackingId:b786d4d1-cbaf-47a8-a3d1-be689cda2a98_G22, SystemTracker:NoSystemTracker, Timestamp:2019-12-27T13:12:40
      </Detail>
  </Error>
  

• Run the following command to check if any port is blocked on the firewall. Ports used are 443 (HTTPS), 5671 and 5672 (AMQP) and 9354 (Net Messaging/SBMP). Depending on the library you use, other ports are also used. Here's the sample command that checks whether the 5671 port is blocked.

  tnc <yournamespacename>.servicebus.windows.net -port 5671
  

  On Linux:

  telnet <yournamespacename>.servicebus.windows.net 5671
  

• When there are intermittent connectivity issues, run the following command to check if there are any dropped packets. This command tries to establish 25 different TCP connections every 1 second with the service. Then, you can check how many of them succeeded/failed and also see TCP connection latency. You can download the psping tool from here.

  .\psping.exe -n 25 -i 1 -q <yournamespace>.servicebus.windows.net:5671 -nobanner     
  

  You can use equivalent commands if you're using other tools such as tnc, ping, and so on.

• Obtain a network trace if the previous steps don't help and analyze it using tools such as Wireshark. Contact Microsoft Support if needed.

• To find the right IP addresses to add to allowlist for your connections, see What IP addresses do I need to add to allowlist.

TLS certificate chain and intermediate certificate issues

Service Bus endpoints (*.servicebus.windows.net) present a TLS certificate that chains to a public root certificate authority (CA). Microsoft periodically rotates the TLS certificates and the intermediate CAs in that chain. If your client's trust store is missing an updated intermediate CA, or if your client pins a specific intermediate or leaf certificate, the TLS handshake fails after a rotation even though nothing changed in your application.

Symptoms include a TLS or SSL handshake failure, a certificate chain validation error such as unable to get local issuer certificate, or a connection that worked before a certificate rotation and starts failing afterward.

To troubleshoot this problem:

• Trust the root CAs rather than pinning intermediate or leaf certificates. Microsoft rotates intermediate certificates, so trusting the root keeps your client working across rotations. For the current root and intermediate CAs used by Azure services, see Azure Certificate Authority details.
• Update the operating system or runtime trust store to include the current CA certificates. On Linux, update the CA bundle, for example, the ca-certificates package. For Java, make sure the JRE cacerts truststore is current, because Java validates certificates against its own truststore rather than the operating system's.
• If you use a custom or corporate trust store, add the current Azure root and intermediate CAs to it.
• Confirm that any intercepting proxy or TLS-inspection appliance presents a certificate chain your client trusts.

Issues that might occur with service upgrades/restarts

Symptoms

• Requests might be momentarily throttled.
• There might be a drop in incoming messages/requests.
• The log file might contain error messages.
• The applications might be disconnected from the service for a few seconds.

Cause

Backend service upgrades and restarts might cause these issues in your applications.

Resolution

If the application code uses SDK, the retry policy is already built in and active. The application reconnects without significant impact to the application/workflow.

Unauthorized access: Send claims are required

Symptoms

You might see this error when attempting to access a Service Bus topic from Visual Studio on an on-premises computer using a user-assigned managed identity with send permissions.

Service Bus Error: Unauthorized access. 'Send' claim\(s\) are required to perform this operation.

Cause

The identity doesn't have permissions to access the Service Bus topic.

Resolution

To resolve this error, install the Microsoft.Azure.Services.AppAuthentication library. For more information, see Local development authentication.

To learn how to assign permissions to roles, see Authenticate a managed identity with Microsoft Entra ID to access Azure Service Bus resources.

Service Bus Exception: Put token failed

Symptoms

You receive the following error message:

Microsoft.Azure.ServiceBus.ServiceBusException: Put token failed. status-code: 403, status-description: The maximum number of '1000' tokens per connection has been reached.

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.

Cause

Number of authentication tokens for concurrent links in a single connection to a Service Bus namespace exceeded the limit: 1000.

Resolution

Do one of the following steps:

• Reduce the number of concurrent links in a single connection or use a new connection
• Use SDKs for Azure Service Bus, which ensures that you don't get into this situation (recommended)

Resource locks don't work when using the data plane SDK

Symptoms

You configured a delete lock on a Service Bus namespace, but you're able to delete resources in the namespace (queues, topics, etc.) by using the Service Bus Explorer.

Cause

Resource lock is preserved in Azure Resource Manager (control plane) and it doesn't prevent the data plane SDK call from deleting the resource directly from the namespace. The standalone Service Bus Explorer uses the data plane SDK, so the deletion goes through.

Resolution

We recommend that you use the Azure Resource Manager based API via Azure portal, PowerShell, CLI, or Resource Manager template to delete entities so that the resource lock prevents the resources from being accidentally deleted.

Entity is no longer available

Symptoms

You see an error that the entity is no longer available.

Cause

The resource might have been deleted. Follow these steps to identify why the entity was deleted.

• Check the activity log to see if there's an Azure Resource Manager request for deletion.
• Check the operational log to see if there was a direct API call for deletion. To learn how to collect an operational log, see Monitor Azure Service Bus. For the schema and an example of an operation log, see Operation logs
• Check the operation log to see if there was an autodeleteonidle related deletion.

Entity names show tilde (~) instead of forward slash (/)

Symptoms

Entity names in the Azure portal, CLI, or ARM API responses show ~ characters, for example orders~us~west instead of orders/us/west.

Cause

Service Bus supports hierarchical entity names with / as the path separator, but Azure Resource Manager doesn't allow / in resource names. Service Bus translates ~ to / at the ARM boundary.

Resolution

This is expected behavior. The underlying entity name uses /. The ~ appears only in ARM-based tools (portal, CLI, PowerShell, ARM templates). Service Bus SDKs and AMQP clients see the actual / name. For details, see Entity names with forward slashes.

Next steps

See the following articles:

• Azure Resource Manager exceptions. It list exceptions generated when interacting with Azure Service Bus using Azure Resource Manager (via templates or direct calls).
• Messaging exceptions. It provides a list of exceptions generated by .NET Framework for Azure Service Bus.