Tutorial: Configuring an Amazon SQS dead-letter queue - Amazon Simple Queue Service

Tutorial: Configuring an Amazon SQS dead-letter queue

A dead-letter queue is a queue that other (source) queues can target for messages that can't be processed (consumed) successfully. In this tutorial you learn how to create an Amazon SQS source queue and to configure a second queue as a dead-letter queue for it. For more information, see Amazon SQS dead-letter queues.


When you designate a queue to be a source queue, a dead-letter queue is not created automatically. You must first create a standard or FIFO queue before designating it a dead-letter queue. This tutorial assumes you already have a normal FIFO queue named MyDeadLetterQueue.fifo.

The dead-letter queue of a FIFO queue must also be a FIFO queue. Similarly, the dead-letter queue of a standard queue must also be a standard queue.

AWS Management Console

  1. Sign in to the Amazon SQS console.

  2. Choose Create New Queue.

  3. On the Create New Queue page, ensure that you're in the correct region and then type the Queue Name.


    The name of a FIFO queue must end with the .fifo suffix.

  4. Standard is selected by default. Choose FIFO.

  5. Choose Configure Queue.

  6. In this example, you enable the redrive policy for your new queue, set the MyDeadLetterQueue.fifo queue as the dead-letter queue, and set the number of maximum receives to 50.

    To configure the dead-letter queue, choose Use Redrive Policy.

    Enter the name of the existing Dead Letter Queue to which you want sources queues to send messages.

    To configure the number of times that a message can be received before being sent to a dead-letter queue, set Maximum Receives to a value between 1 and 1,000.


    The Maximum Receives setting applies only to individual messages.

    Choose Create Queue.

    Your new queue is configured to use a dead-letter queue, created, and selected in the queue list.


    When you create a queue, it can take a short time for the queue to propagate throughout Amazon SQS.

    Your queue's Maximum Receives and Dead Letter Queue ARN are displayed on the Redrive Policy tab.

AWS SDK for Java

The following example uses the AWS Java SDK. To install and set up the SDK, see Set up the AWS SDK for Java in the AWS SDK for Java Developer Guide.

Before you run the example code, configure your AWS credentials. For more information, see Set up AWS Credentials and Region for Development in the AWS SDK for Java Developer Guide.

To configure a dead-letter queue

The following example Java code creates two standard queues and configures one queue to act as a source queue for the other—a dead-letter queue.

/* * Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). * You may not use this file except in compliance with the License. * A copy of the License is located at * * https://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either * express or implied. See the License for the specific language governing * permissions and limitations under the License. * */ import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.GetQueueAttributesRequest; import com.amazonaws.services.sqs.model.GetQueueAttributesResult; import com.amazonaws.services.sqs.model.QueueAttributeName; import com.amazonaws.services.sqs.model.SetQueueAttributesRequest; import java.util.Scanner; public class SQSDeadLetterQueueExample { public static void main(String[] args) { final Scanner input = new Scanner(System.in); System.out.print("Enter the source queue name: "); final String sourceQueueName = input.nextLine(); System.out.print("Enter the dead-letter queue name: "); final String deadLetterQueueName = input.nextLine(); /* * Create a new instance of the builder with all defaults (credentials * and region) set automatically. For more information, see * Creating Service Clients in the AWS SDK for Java Developer Guide. */ final AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient(); try { // Create a source queue. sqs.createQueue(sourceQueueName); // Create a dead-letter queue. sqs.createQueue(deadLetterQueueName); // Get the dead-letter queue ARN. final String deadLetterQueueUrl = sqs.getQueueUrl(deadLetterQueueName) .getQueueUrl(); final GetQueueAttributesResult deadLetterQueueAttributes = sqs.getQueueAttributes( new GetQueueAttributesRequest(deadLetterQueueUrl) .withAttributeNames("QueueArn")); final String deadLetterQueueArn = deadLetterQueueAttributes.getAttributes().get("QueueArn"); // Set the dead-letter queue for the source queue using the redrive policy. final String sourceQueueUrl = sqs.getQueueUrl(sourceQueueName) .getQueueUrl(); final SetQueueAttributesRequest request = new SetQueueAttributesRequest() .withQueueUrl(sourceQueueUrl) .addAttributesEntry(QueueAttributeName.RedrivePolicy.toString(), "{\"maxReceiveCount\":\"5\", \"deadLetterTargetArn\":\"" + deadLetterQueueArn + "\"}"); sqs.setQueueAttributes(request); System.out.println("Set queue " + sourceQueueName + " as source queue " + "for dead-letter queue " + deadLetterQueueName + "."); } catch (final AmazonServiceException ase) { System.out.println("Caught an AmazonServiceException, which means " + "your request made it to Amazon SQS, but was " + "rejected with an error response for some reason."); System.out.println("Error Message: " + ase.getMessage()); System.out.println("HTTP Status Code: " + ase.getStatusCode()); System.out.println("AWS Error Code: " + ase.getErrorCode()); System.out.println("Error Type: " + ase.getErrorType()); System.out.println("Request ID: " + ase.getRequestId()); } catch (final AmazonClientException ace) { System.out.println("Caught an AmazonClientException, which means " + "the client encountered a serious internal problem while " + "trying to communicate with Amazon SQS, such as not " + "being able to access the network."); System.out.println("Error Message: " + ace.getMessage()); } } }

To configure a dead-letter queue and send, receive, and delete a message

  1. Copy the example program for a standard queue or a FIFO queue.

  2. Set a string that contains JSON-formatted parameters and values for the RedrivePolicy queue attribute:

    final String redrivePolicy = "{\"maxReceiveCount\":\"5\", \"deadLetterTargetArn\":\"arn:aws:sqs:us-east-2:123456789012:MyDeadLetterQueue\"}";
  3. Use the CreateQueue or SetQueueAttributesRequest action to configure the RedrivePolicy queue attribute:

    final SetQueueAttributesRequest queueAttributes = new SetQueueAttributesRequest(); final Map<String,String> attributes = new HashMap<String,String>(); attributes.put("RedrivePolicy", redrivePolicy); queueAttributes.setAttributes(attributes); queueAttributes.setQueueUrl(myQueueUrl); sqs.setQueueAttributes(queueAttributes);
  4. Compile and run your program.

    The dead-letter queue is configured and the message is sent, received, and deleted.