Dead letter queues in Azure - Commands & Configuration

Introduction

Sometimes messages sent to a queue cannot be processed due to errors or issues. Dead letter queues help by storing these problem messages separately so they don't block the main queue and can be reviewed later.

When a message cannot be delivered or processed after several attempts and you want to keep it for troubleshooting.

When you want to avoid losing messages that cause errors in your application.

When you want to monitor and analyze failed messages separately from successful ones.

When you want to prevent problematic messages from blocking the processing of other messages.

When you want to implement retry or alerting mechanisms based on failed messages.

Config File - azure-deadletter-queue.json

azure-deadletter-queue.json

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "type": "Microsoft.ServiceBus/namespaces/queues",
      "apiVersion": "2022-10-01",
      "name": "my-servicebus-namespace/my-main-queue",
      "properties": {
        "enableDeadLetteringOnMessageExpiration": true,
        "maxDeliveryCount": 5
      }
    }
  ]
}

This Azure Resource Manager template creates a Service Bus queue named my-main-queue inside the namespace my-servicebus-namespace.

The key properties are:

• enableDeadLetteringOnMessageExpiration: Enables messages that expire to be moved to the dead letter queue.
• maxDeliveryCount: Sets how many times a message can be delivered before moving to the dead letter queue.
• The dead letter queue itself is automatically created as a sub-queue named $DeadLetterQueue.

Commands

Create a Service Bus namespace to hold queues and topics.

Terminal

az servicebus namespace create --resource-group example-rg --name my-servicebus-namespace --location eastus

Expected Output

{

  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.ServiceBus/namespaces/my-servicebus-namespace",

  "location": "eastus",

  "name": "my-servicebus-namespace",

  "provisioningState": "Succeeded",

  "resourceGroup": "example-rg",

  "sku": {

    "name": "Standard",

    "tier": "Standard"

  },

  "type": "Microsoft.ServiceBus/namespaces"

}

→

--resource-group - Specifies the Azure resource group to create the namespace in.

→

--name - Sets the name of the Service Bus namespace.

→

--location - Sets the Azure region for the namespace.

Create the main queue with dead lettering enabled and set max delivery attempts before dead lettering.

Terminal

az servicebus queue create --resource-group example-rg --namespace-name my-servicebus-namespace --name my-main-queue --max-delivery-count 5 --enable-dead-lettering-on-message-expiration true

Expected Output

{

  "autoDeleteOnIdle": "P10675199DT2H48M5.4775807S",

  "deadLetteringOnMessageExpiration": true,

  "defaultMessageTimeToLive": "P14D",

  "duplicateDetectionHistoryTimeWindow": "PT10M",

  "enableBatchedOperations": true,

  "enableDeadLetteringOnMessageExpiration": true,

  "enablePartitioning": false,

  "enableExpress": false,

  "maxDeliveryCount": 5,

  "maxSizeInMegabytes": 1024,

  "name": "my-main-queue",

  "requiresDuplicateDetection": false,

  "status": "Active"

}

→

--max-delivery-count - Number of delivery attempts before moving message to dead letter queue.

→

--enable-dead-lettering-on-message-expiration - Enables dead lettering for expired messages.

Check the properties of the queue to confirm dead letter settings.

Terminal

az servicebus queue show --resource-group example-rg --namespace-name my-servicebus-namespace --name my-main-queue

Expected Output

{

  "name": "my-main-queue",

  "maxDeliveryCount": 5,

  "enableDeadLetteringOnMessageExpiration": true,

  "status": "Active"

}

Peek at messages in the dead letter queue to see failed messages without removing them.

Terminal

az servicebus queue deadletter peek --resource-group example-rg --namespace-name my-servicebus-namespace --queue-name my-main-queue --max-message-count 5

Expected Output

[]

→

--max-message-count - Limits the number of messages returned.

Key Concept

If a message fails processing repeatedly, it moves to a special dead letter queue to keep the main queue flowing and allow later inspection.

Common Mistakes

Not enabling dead lettering on the queue properties.

Messages that fail will be lost or block the queue instead of moving to the dead letter queue.

Always set enableDeadLetteringOnMessageExpiration to true and configure maxDeliveryCount.

Trying to send messages directly to the dead letter queue.

Dead letter queues are sub-queues and cannot be written to directly by clients.

Send messages to the main queue and let the system move failed messages to the dead letter queue.

Summary

Create a Service Bus namespace to hold your queues.

Create a queue with dead lettering enabled and set max delivery attempts.

Use CLI commands to verify queue settings and peek at dead letter messages.