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:SetQueueAttributes on my-queue. For the console, also queue:GetQueueAttributes on 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

  1. Open my-queue, then choose Settings.
  2. Under Dead-letter queue, for Queue, choose my-queue-dlq. To remove the dead-letter queue, choose None.
  3. For Receives before moving, enter a number from 1 to 1000.
  4. Choose Save.

Save also saves the settings under Delivery.

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."
Did this page help you?