Edit

Enable dead lettering on message expiration for Azure Service Bus queues and subscriptions

  • Article

Azure Service Bus queues and subscriptions for topics provide a secondary subqueue, called a dead-letter queue (DLQ). The dead-letter queue doesn't need to be explicitly created and can't be deleted or managed independent of the main entity. The purpose of the dead-letter queue is to hold messages that can't be delivered to any receiver, or messages that couldn't be processed. For more information, See Overview of Service Bus dead-letter queues. This article shows you different ways to enable dead lettering for Service Bus queues and subscriptions.

Using Azure portal

When creating a queue or a subscription for a topic in the Azure portal, select Enable dead lettering on message expiration as shown in the following examples.

Create a queue with dead lettering enabled

Enable dead lettering at the time of the queue creation

Create a subscription with dead lettering enabled

Enable dead lettering at the time of the subscription creation

Update the dead lettering on message expiration setting for an existing queue

On the Overview page for your Service Bus queue, select the current value for the Dead lettering on message expiration setting. In the following example, the current value is Disabled. You can enable or disable dead lettering on message expiration in the popup window.

Enable dead-lettering on message expiration for an existing queue

Update the dead lettering on message expiration setting for an existing subscription

On the Overview page for your Service Bus subscription, select the current value for the Dead lettering on message expiration setting. In the following example, the current value is Disabled. You can enable or disable dead lettering on message expiration in the popup window.

Enable dead-lettering on message expiration for an existing subscription

Using Azure CLI

To create a queue with dead lettering on message expiration enabled, use the az servicebus queue create command with --enable-dead-lettering-on-message-expiration set to true.

az servicebus queue create \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --enable-dead-lettering-on-message-expiration true

To enable the dead lettering on message expiration setting for an existing queue, use the az servicebus queue update command with --enable-dead-lettering-on-message-expiration set to true.

az servicebus queue update \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --enable-dead-lettering-on-message-expiration true

To create a subscription to a topic with dead lettering on message expiration enabled, use the az servicebus topic subscription create command with --enable-dead-lettering-on-message-expiration set to true.

az servicebus topic subscription create \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --topic-name mytopic \
    --name mysubscription \
    --enable-dead-lettering-on-message-expiration true

To enable the dead lettering on message expiration setting for a subscription to a topic, use the az servicebus topic subscription update command with --enable-dead-lettering-on-message-expiration set true.

az servicebus topic subscription update \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --topic-name mytopic \
    --name mysubscription \
    --enable-dead-lettering-on-message-expiration true

Note

If you specify a queue or topic by using the --forward-dead-lettered-messages-to parameter, Event Grid automatically forwards dead-lettered messages to that queue or topic. Here's an example: az servicebus queue create --resource-group mysbusrg --namespace-name mysbusns --name myqueue --enable-dead-lettering-on-message-expiration true --forward-dead-lettered-messages-to myqueue2.

Using Azure PowerShell

To create a queue with dead lettering on message expiration enabled, use the New-AzServiceBusQueue command with -DeadLetteringOnMessageExpiration set to $True.

New-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue `
    -DeadLetteringOnMessageExpiration $True

To enable the dead lettering on message expiration setting for an existing queue, use the Set-AzServiceBusQueue command as shown in the following example.

$queue=Get-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue 

$queue.DeadLetteringOnMessageExpiration=$True

Set-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue `
    -QueueObj $queue

To create a subscription for a topic with dead lettering on message expiration enabled, use the New-AzServiceBusSubscription command with -DeadLetteringOnMessageExpiration set to $True.

New-AzServiceBusSubscription -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -TopicName mytopic `
    -SubscriptionName mysubscription `
    -DeadLetteringOnMessageExpiration $True

To enable the dead lettering on message expiration setting for an existing subscription, see the following example.

$subscription=Get-AzServiceBusSubscription -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -TopicName mytopic `
    -SubscriptionName mysub

$subscription.DeadLetteringOnMessageExpiration=$True

Set-AzServiceBusSubscription -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -Name mytopic `
    -SubscriptionName mysub `
    -SubscriptionObj $subscription

Note

If you specify a queue or topic by using the -ForwardDeadLetteredMessagesTo parameter, Event Grid automatically forwards dead-lettered messages to that queue or topic.

Using Azure Resource Manager template

To create a queue with dead lettering on message expiration enabled, set deadLetteringOnMessageExpiration in the queue properties section to true. For more information, see Microsoft.ServiceBus namespaces/queues template reference.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "serviceBusNamespaceName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Service Bus namespace"
      }
    },
    "serviceBusQueueName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Queue"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.ServiceBus/namespaces",
      "apiVersion": "2018-01-01-preview",
      "name": "[parameters('serviceBusNamespaceName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard"
      },
      "properties": {},
      "resources": [
        {
          "type": "Queues",
          "apiVersion": "2017-04-01",
          "name": "[parameters('serviceBusQueueName')]",
          "dependsOn": [
            "[resourceId('Microsoft.ServiceBus/namespaces', parameters('serviceBusNamespaceName'))]"
          ],
          "properties": {
            "deadLetteringOnMessageExpiration": true
          }
        }
      ]
    }
  ]
}

To create a subscription for a topic with dead lettering on message expiration enabled, set deadLetteringOnMessageExpiration in the queue properties section to true. For more information, see Microsoft.ServiceBus namespaces/topics/subscriptions template reference.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "service_BusNamespace_Name": {
      "type": "string",
      "metadata": {
        "description": "Name of the Service Bus namespace"
      }
    },
    "serviceBusTopicName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Topic"
      }
    },
    "serviceBusSubscriptionName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Subscription"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    }
  },
  "resources": [
    {
      "apiVersion": "2018-01-01-preview",
      "name": "[parameters('service_BusNamespace_Name')]",
      "type": "Microsoft.ServiceBus/namespaces",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard"
      },
      "properties": {},
      "resources": [
        {
          "apiVersion": "2017-04-01",
          "name": "[parameters('serviceBusTopicName')]",
          "type": "topics",
          "dependsOn": [
            "[resourceId('Microsoft.ServiceBus/namespaces/', parameters('service_BusNamespace_Name'))]"
          ],
          "properties": {
            "maxSizeInMegabytes": 1024
          },
          "resources": [
            {
              "apiVersion": "2017-04-01",
              "name": "[parameters('serviceBusSubscriptionName')]",
              "type": "Subscriptions",
              "dependsOn": [
                "[parameters('serviceBusTopicName')]"
              ],
              "properties": {
                "deadLetteringOnMessageExpiration": true
              }
            }
          ]
        }
      ]
    }
  ]
}

Note

If you specify a queue or topic for the forwardDeadLetteredMessagesTo property, Event Grid automatically forwards dead-lettered messages to that queue or topic.

Next steps

Try the samples in the language of your choice to explore Azure Service Bus features.

Find samples for the older .NET and Java client libraries below:

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.