Menu
Amazon Simple Queue Service
Developer Guide (API Version 2012-11-05)

Using Amazon SQS Dead Letter Queues

Amazon SQS now provides support for dead letter queues. A dead letter queue is a queue that other (source) queues can target to send messages that for some reason could not be successfully processed. A primary benefit of using a dead letter queue is the ability to sideline and isolate the unsuccessfully processed messages. You can then analyze any messages sent to the dead letter queue to try and determine why they were not successfully processed.

To specify a dead letter queue, you can use the AWS Management Console or the query API. This must be done for each (source) queue that will send messages to a dead letter queue. You can have multiple (source) queues target a single dead letter queue.

Important

You must use the same AWS account to create the queue which will be used as a dead letter queue and the other (source) queues that will send messages to the dead letter queue. Dead letter queues also must reside in the same region as the other queues that use the dead letter queue. For example, if you created a queue in the US East (N. Virginia) region and you want to use a dead letter queue with that queue, then both queues must be in the US East (N. Virginia) region.

Setting up Dead Letter Queue with the AWS Management Console

You can use the AWS Management Console to configure dead letter queue functionality so that messages, which for some reason could not be successfully processed, are sent to a specified dead letter queue. This is accomplished by first selecting the source queue's Use Redrive Policy check box for existing and newly created queues.

Next, enter the name of the queue to which messages will be sent from the source queues.

You then set the Maximum Receives to a value between 1 and 1000.

The following figure shows the MyQueue queue, which has the Redrive Policy configured to have messages sent to the MyDeadLetterQueue queue.

Using Dead Letter Queue with the Amazon SQS API

To specify a dead letter queue with the query API, you call either the CreateQueue or SetQueueAttributes actions and set the maxReceiveCount and deadLetterTargetArn parameters for the RedrivePolicy queue attribute.

You can set maxReceiveCount to a value between 1 and 1000. The deadLetterTargetArn value is the Amazon Resource Name (ARN) of the queue that will receive the dead letter messages.

The following Java example shows how to use SetQueueAttributes to set the maxReceiveCount and deadLetterTargetArn parameters for the RedrivePolicy queue attribute. This example is based on the SimpleQueueServiceSample.java sample from the AWS SDK for Java.

First, a string is set that contains JSON formatted parameters and values for the RedrivePolicy queue attribute:


String redrivePolicy = "{\"maxReceiveCount\":\"5\", \"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:123456789012:MyDeadLetterQueue\"}";
        

Next, SetQueueAttributesRequest is used to set the RedrivePolicy queue attribute:


SetQueueAttributesRequest queueAttributes = new SetQueueAttributesRequest();
Map<String,String> attributes = new HashMap<String,String>();            
attributes.put("RedrivePolicy", redrivePolicy);            
queueAttributes.setAttributes(attributes);
queueAttributes.setQueueUrl(myQueueUrl);
sqs.setQueueAttributes(queueAttributes);
        

An API query request for this example should look similar to the following:


http://sqs.us-east-1.amazonaws.com/123456789012/MySourceQueue 
?Action=SetQueueAttributes
&Attribute.1.Value=%7B%22maxReceiveCount%22%3A%225%22%2C+%22deadLetterTargetArn%22%3A%22arn%3Aaws%3Asqs%3Aus-east-1%3A123456789012%3AMyDeadLetterQueue%22%7D
&Version=2012-11-05
&Attribute.1.Name=RedrivePolicy
        

Note

Queue names and queue URLs are case-sensitive.

The API query response should look similar to the following:


<SetQueueAttributesResponse xmlns="http://queue.amazonaws.com/doc/2012-11-05/">
    <ResponseMetadata>
        <RequestId>40945605-b328-53b5-aed4-1cc24a7240e8</RequestId>
    </ResponseMetadata>
</SetQueueAttributesResponse>
        

Issue: Viewing Messages with the Amazon SQS Console Can Cause the Messages to be Moved to a Dead Letter Queue

If you view a message in the Amazon SQS console the number of times that is specified in the corresponding queue's redrive policy, the message is moved to the corresponding queue's dead letter queue.

This behavior happens because Amazon SQS counts viewing a message in the Amazon SQS console against the corresponding queue's redrive policy.

To adjust this behavior, either increase the Maximum Receives setting for the corresponding queue's redrive policy, or do not view the corresponding queue's messages in the Amazon SQS console.

To reproduce this behavior:

  1. In the Amazon SQS console, create 2 queues named MyQueueA and MyQueueB.

  2. Specify the settings for MyQueueA: in the list of queues, choose (check) MyQueueA. Then choose Queue Actions, Configure Queue.

  3. For Dead Letter Queue Settings, choose (check) Use Redrive Policy.

  4. For Dead Letter Queue, type MyQueueB. (This sets MyQueueB as the dead letter queue for MyQueueA.)

  5. For Maximum Receives, type 2. (This means that after a message is viewed 2 times, the message will be sent to the dead letter queue (MyQueueB).) Then choose Save Changes.

  6. Send some messages to MyQueueA: with MyQueueA still chosen (checked) in the list of queues, choose Queue Actions, Send a Message.

  7. With the Message Body tab already chosen, type some message text, and then choose Send Message.

  8. Chose Send Another Message, and repeat step 7 to send another message to MyQueueA. Then choose Close.

  9. View the messages that you sent to MyQueueA: with MyQueueA still chosen (checked) in the list of queues, choose Queue Actions, View/Delete Messages.

  10. Choose Start Polling for Messages. The messages from steps 7 and 8 are displayed.

  11. Wait for 1 minute, and then choose Start Polling for Messages again. The messages from steps 7 and 8 are displayed again. (Notice that Receive Count for both messages is now 2. This is equal to the Maximum Receives value that you specified in step 5.)

  12. Wait for 1 minute, and then choose Start Polling for Messages again. This time, the messages from steps 7 and 8 are no longer displayed. (This is because you already viewed the messages 2 times, which is equal to the Maximum Receives value that you specified in step 5.) Choose Close.

  13. View the messages in the dead letter queue for MyQueueA: in the list of queues, unchoose (uncheck) MyQueueA. Then choose (check) MyQueueB, and choose Queue Actions, View/Delete Messages.

  14. Choose Start Polling for Messages. The messages from steps 7 and 8 are displayed. (This is because MyQueueB is the dead letter queue for MyQueueA.)