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

Using Amazon SQS Dead Letter Queues

Amazon SQS provides support for dead letter queues. A dead letter queue is a queue that other (source) queues can target for messages that cannot be processed successfully. You can set aside and isolate these messages in the dead letter queue to determine why their processing did not succeed.

To specify a dead letter queue, you can use the AWS Management Console or the query API. You must do this for each queue that will send messages to a dead letter queue. Multiple queues can target a single dead letter queue.

Important

You must use the same AWS account to create the dead letter queue and the other queues that will send messages to the dead letter queue. Also, dead letter queues must reside in the same region as the other queues that use the dead letter queue. For example, if you create 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 a Dead Letter Queue with the AWS Management Console

You can use the AWS Management Console to send messages that could not be processed successfully to a specified dead letter queue.

  1. For existing and newly-created source queues, select Use Redrive Policy.

  2. Type the name of the queue to which source queues will send messages.

  3. Set Maximum Receives to a value between 1 and 1,000.

    Note

    The Maximum Receives setting (the number of times that a message can be received before being sent to a dead letter queue) applies only to individual messages.

The following figure shows MyQueue with a Redrive Policy configured to send messages to MyDeadLetterQueue.

Using a Dead Letter Queue with the Amazon SQS API

To specify a dead letter queue using the query API, 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 1,000. 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, set a string 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, use SetQueueAttributesRequest 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

Amazon SQS counts viewing a message in the Amazon SQS console against the corresponding queue's redrive policy. Thus, if you view a message in the Amazon SQS console the number of times specified in the corresponding queue's redrive policy, the message is moved to the corresponding queue's dead letter queue.

To adjust this behavior you can either increase the Maximum Receives setting for the corresponding queue's redrive policy, or avoid viewing the corresponding queue's messages in the Amazon SQS console.

To reproduce this behavior:

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

  2. From the list of queues, select MyQueueA. Then choose Queue Actions, Configure Queue.

    The Configure MyQueueA dialog box is displayed.

  3. For Dead Letter Queue Settings, select Use Redrive Policy.

    For Dead Letter Queue, type MyQueueB. (MyQueueB will become the dead letter queue for MyQueueA.)

    For Maximum Receives, type 2 and then choose Save Changes. (After a message is viewed twice, it will be sent to MyQueueB, the dead letter queue.)

  4. With MyQueueA still selected in the list of queues, choose Queue Actions, Send a Message.

    The Send a Message to MyQueueA dialog box is displayed.

  5. On the Message Body tab, type any message text, and then choose Send Message.

    Choose Send Another Message, and then send another message to MyQueueA. Then choose Close.

  6. With MyQueueA still selected in the list of queues, choose Queue Actions, View/Delete Messages.

    The Start Polling for Messages dialog box is displayed.

  7. Choose Start Polling for Messages. The messages you sent are displayed.

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

  9. Wait for 1 minute, and then choose Start Polling for Messages again. This time, the messages you sent are no longer displayed. (You have already viewed the messages twice. This is equal to the Maximum Receives value that you specified.) Choose Close.

  10. In the list of queues, clear MyQueueA. Then, select MyQueueB, and choose Queue Actions, View/Delete Messages.

    Choose Start Polling for Messages. The messages you sent are displayed. (MyQueueB is now the dead letter queue for MyQueueA.)

Issue: NumberOfMessagesSent and NumberOfMessagesReceived for the Dead Letter Queue Do Not Match

If you send a message to a dead letter queue manually, it will be captured by the NumberOfMessagesSent metric.

However, if you send a message to a dead letter queue with the SendMessage action, it will not be captured by theNumberOfMessagesSent metric. In this case, it is possible for the values of the NumberOfMessagesSent and NumberOfMessagesReceived metrics to be different.