What happens to a message when its dequeue count exceeds maxDequeueCount?

It's automatically moved to the configured poison queue rather than being redelivered again, this requires the consumer's own retry/processing logic to actually check and increment dequeue count and move the message (Azure Queue Storage doesn't natively auto-move to a poison queue without consumer-side logic implementing this pattern using the queue SDK's dequeue count property), the poisonQueue configuration here documents the intended destination and threshold your consumer code needs to implement against.

Does a visibilityTimeout that's too short cause message loss?

Not loss exactly, but duplicate processing, if a consumer is still legitimately processing a message when its visibility timeout expires, the message becomes visible again and a second consumer can dequeue and process the same message concurrently, for a non-idempotent operation (like charging a payment), this produces a real duplicate-processing bug, not just inefficiency.

Can messageTtl be set to never expire?

Yes, Queue Storage supports an infinite TTL for messages that should never expire regardless of how long they sit in the queue, but for most operational queues, an explicit, bounded TTL matching the message's actual useful lifetime (as the example sets per queue) is preferable, since it prevents an old, no-longer-actionable message from lingering and potentially getting processed long after it stopped being relevant.

Azure Queue Storage Config Builder

StorageAzure

Build Queue Storage message configs with visibility timeouts, TTL, poison queues, consumer batching, and polling settings.

Azure Queue Storage Configuration

Build Queue Storage message configs with visibility timeouts, TTL, poison queues, consumer batching, and polling settings.

Required Fields

storageAccountNamequeuesqueues[0].queueNamequeues[0].messageSettings.visibilityTimeoutqueues[0].messageSettings.messageTtl

{
  "storageAccountName": "stcontosoqueues",
  "resourceGroup": "rg-messaging",
  "location": "eastus2",
  "queues": [
    {
      "queueName": "order-processing",
      "messageSettings": {
        "visibilityTimeout": "PT5M",
        "messageTtl": "P7D",
        "maxMessageSizeKB": 64
      },
      "poisonQueue": {
        "name": "order-processing-poison",
        "maxDequeueCount": 5
      },
      "exampleMessage": {
        "orderId": "ORD-2026-00042",
        "customerId": "CUST-12345",
        "action": "process",
        "items": [
          { "sku": "PROD-001", "quantity": 2, "unitPrice": 29.99 }
        ],
        "priority": "normal",
        "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "consumerConfig": {
        "pollingInterval": "PT1S",
        "batchSize": 16,
        "maxPollingInterval": "PT1M",
        "concurrency": 4
      }
    },
    {
      "queueName": "email-notifications",
      "messageSettings": {
        "visibilityTimeout": "PT2M",
        "messageTtl": "P1D",
        "maxMessageSizeKB": 64
      },
      "poisonQueue": {
        "name": "email-notifications-poison",
        "maxDequeueCount": 3
      },
      "exampleMessage": {
        "to": "user@contoso.com",
        "templateId": "order-confirmation",
        "variables": {
          "orderNumber": "ORD-2026-00042",
          "customerName": "Jane Doe"
        }
      },
      "consumerConfig": {
        "pollingInterval": "PT5S",
        "batchSize": 32,
        "concurrency": 2
      }
    },
    {
      "queueName": "scheduled-tasks",
      "messageSettings": {
        "visibilityTimeout": "PT10M",
        "messageTtl": "P14D",
        "maxMessageSizeKB": 64
      },
      "poisonQueue": {
        "name": "scheduled-tasks-poison",
        "maxDequeueCount": 3
      }
    }
  ],
  "storageSettings": {
    "redundancy": "GRS",
    "accessTier": "Hot",
    "enableHttpsTrafficOnly": true,
    "minimumTlsVersion": "TLS1_2"
  },
  "metadata": {
    "environment": "production",
    "team": "backend"
  }
}

Generated Output

Output will appear here...

About This Tool

Build Azure Queue Storage configurations with per-queue visibilityTimeout, messageTtl, and a poisonQueue with maxDequeueCount, the mechanism that automatically moves a message to a separate poison queue after it's been dequeued and failed to be deleted that many times, preventing one malformed or bug-triggering message from being retried indefinitely and blocking queue processing throughput. visibilityTimeout needs to genuinely exceed the consumer's actual processing time for a given message type, order-processing-poison at PT5M versus email-notifications-poison at PT2M reflects that these two queues' consumers have different expected processing durations, a visibility timeout shorter than actual processing time causes the same message to become visible and get picked up by a second consumer while the first is still legitimately working on it.

When to Use This Tool

•Setting visibilityTimeout comfortably longer than the queue's actual worst-case consumer processing time (order-processing at 5 minutes versus the lighter email-notifications queue at 2 minutes), so a slow-but-successful processing run doesn't get duplicated by a second consumer picking up the same message.
•Tuning maxDequeueCount lower (3) for a queue where repeated failures likely indicate a genuinely bad message (email-notifications, scheduled-tasks) versus higher (5) for order-processing where transient downstream failures might legitimately need more retry attempts before being deemed truly poison.
•Setting messageTtl based on how long a message is still actionable if delayed (P7D for order processing versus P1D for time-sensitive email notifications), since a message surviving past its useful window just consumes queue storage for something that should no longer be processed.
•Tuning consumerConfig's batchSize and concurrency to match the downstream processing capacity, a higher batchSize with insufficient concurrency just means messages sit dequeued-but-unprocessed longer, risking visibility timeout expiry before they're actually handled.

Pro Tips

TIP

Always set visibilityTimeout meaningfully longer than the queue's actual worst-case consumer processing time, not just the typical case, a timeout tuned to average processing time causes duplicate processing on every above-average-duration message.

TIP

maxDequeueCount and poison queue handling only work if consumer code actually implements checking and moving the message, this configuration documents intent, verify your actual consumer implementation honors it rather than assuming Queue Storage enforces it automatically.

TIP

Match messageTtl to the message's genuine useful lifetime per queue, a one-size-fits-all TTL across queues with very different actionability windows (order processing vs. time-sensitive notifications) either expires messages too early or lets stale ones linger too long.

How It Works Under the Hood

The builder validates that storageAccountName, queues, and the first queue's queueName/messageSettings.visibilityTimeout/messageSettings.messageTtl all resolve before accepting the JSON as a valid combined queue configuration specification; it can't verify consumer code actually implements the documented poison-queue and dequeue-count handling, that's an application-level responsibility the configuration only documents intent for.

Frequently Asked Questions

What happens to a message when its dequeue count exceeds maxDequeueCount?: It's automatically moved to the configured poison queue rather than being redelivered again, this requires the consumer's own retry/processing logic to actually check and increment dequeue count and move the message (Azure Queue Storage doesn't natively auto-move to a poison queue without consumer-side logic implementing this pattern using the queue SDK's dequeue count property), the poisonQueue configuration here documents the intended destination and threshold your consumer code needs to implement against.
Does a visibilityTimeout that's too short cause message loss?: Not loss exactly, but duplicate processing, if a consumer is still legitimately processing a message when its visibility timeout expires, the message becomes visible again and a second consumer can dequeue and process the same message concurrently, for a non-idempotent operation (like charging a payment), this produces a real duplicate-processing bug, not just inefficiency.
Can messageTtl be set to never expire?: Yes, Queue Storage supports an infinite TTL for messages that should never expire regardless of how long they sit in the queue, but for most operational queues, an explicit, bounded TTL matching the message's actual useful lifetime (as the example sets per queue) is preferable, since it prevents an old, no-longer-actionable message from lingering and potentially getting processed long after it stopped being relevant.

Related Learning Guides

Storage Account Types22 min read
Cosmos DB Consistency Levels24 min read

Was this tool helpful?

Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.

Azure Queue Storage Config Builder

StorageAzure

Build Queue Storage message configs with visibility timeouts, TTL, poison queues, consumer batching, and polling settings.

Azure Queue Storage Configuration

Build Queue Storage message configs with visibility timeouts, TTL, poison queues, consumer batching, and polling settings.

Required Fields

storageAccountNamequeuesqueues[0].queueNamequeues[0].messageSettings.visibilityTimeoutqueues[0].messageSettings.messageTtl

Generated Output

Output will appear here...

About This Tool

When to Use This Tool

•Setting visibilityTimeout comfortably longer than the queue's actual worst-case consumer processing time (order-processing at 5 minutes versus the lighter email-notifications queue at 2 minutes), so a slow-but-successful processing run doesn't get duplicated by a second consumer picking up the same message.
•Tuning maxDequeueCount lower (3) for a queue where repeated failures likely indicate a genuinely bad message (email-notifications, scheduled-tasks) versus higher (5) for order-processing where transient downstream failures might legitimately need more retry attempts before being deemed truly poison.
•Setting messageTtl based on how long a message is still actionable if delayed (P7D for order processing versus P1D for time-sensitive email notifications), since a message surviving past its useful window just consumes queue storage for something that should no longer be processed.
•Tuning consumerConfig's batchSize and concurrency to match the downstream processing capacity, a higher batchSize with insufficient concurrency just means messages sit dequeued-but-unprocessed longer, risking visibility timeout expiry before they're actually handled.

Pro Tips

TIP

How It Works Under the Hood

Frequently Asked Questions

What happens to a message when its dequeue count exceeds maxDequeueCount?: It's automatically moved to the configured poison queue rather than being redelivered again, this requires the consumer's own retry/processing logic to actually check and increment dequeue count and move the message (Azure Queue Storage doesn't natively auto-move to a poison queue without consumer-side logic implementing this pattern using the queue SDK's dequeue count property), the poisonQueue configuration here documents the intended destination and threshold your consumer code needs to implement against.
Does a visibilityTimeout that's too short cause message loss?: Not loss exactly, but duplicate processing, if a consumer is still legitimately processing a message when its visibility timeout expires, the message becomes visible again and a second consumer can dequeue and process the same message concurrently, for a non-idempotent operation (like charging a payment), this produces a real duplicate-processing bug, not just inefficiency.
Can messageTtl be set to never expire?: Yes, Queue Storage supports an infinite TTL for messages that should never expire regardless of how long they sit in the queue, but for most operational queues, an explicit, bounded TTL matching the message's actual useful lifetime (as the example sets per queue) is preferable, since it prevents an old, no-longer-actionable message from lingering and potentially getting processed long after it stopped being relevant.

Related Learning Guides

Storage Account Types22 min read
Cosmos DB Consistency Levels24 min read

Was this tool helpful?