Set a dead-letter queue
Name the queue that takes a message after a set number of receives without a delete, change the number, or remove the dead-letter queue.
Last updated 18 November 2026View as Markdown
Replace my-queue with the name of your queue and my-queue-dlq with the queue that should take its failed messages. How messages move is described in Dead-letter queues.
Prerequisites
- Permission for
queue:SetQueueAttributeson my-queue. For the console, alsoqueue:GetQueueAttributeson it, to open its page. - my-queue-dlq exists in the same organization and region, is not my-queue itself, and is of the same type: FIFO for a FIFO queue, standard for a standard queue.
Set or change the dead-letter queue
- Open my-queue, then choose Settings.
- Under Dead-letter queue, for Queue, choose my-queue-dlq. To remove the dead-letter queue, choose None.
- For Receives before moving, enter a number from 1 to 1000.
- Choose Save.
Save also saves the settings under Delivery.
dcloud queue queues set-attributes my-queue --dead-letter-queue '{"name":"my-queue-dlq","maxReceiveCount":5}'PATCH /queue/api/queues/my-queue
{ "deadLetterQueue": { "name": "my-queue-dlq", "maxReceiveCount": 5 } }To remove the dead-letter queue:
PATCH /queue/api/queues/my-queue
{ "deadLetterQueue": null }resource "dcloud_queue" "main" {
name = "my-queue"
dead_letter_queue = jsonencode({
name = "my-queue-dlq"
maxReceiveCount = 5
})
}Removing dead_letter_queue from the configuration does not remove the dead-letter queue from the
queue; use the console or the API for that.
Result
From now on a message of my-queue moves to my-queue-dlq once it has been received the given number of times without being deleted. After you remove the dead-letter queue, failed messages are delivered again until they expire.
When the change is refused
400"A queue cannot be its own dead-letter queue."404"There is no queue named “my-queue-dlq” to use as the dead-letter queue."400"The dead-letter queue of a FIFO queue must also be a FIFO queue." or "The dead-letter queue of a standard queue must also be a standard queue."
Related
Did this page help you?