How to Configure Dead Letter Queue in AWS SQS

To configure a dead letter queue (DLQ) in AWS SQS, create a standard or FIFO queue to act as the DLQ, then set the RedrivePolicy on your main queue to point to this DLQ with a maximum receive count. This setup moves messages that fail processing multiple times to the DLQ for later inspection.

Syntax

The key part of configuring a dead letter queue in AWS SQS is the RedrivePolicy attribute on the main queue. It requires two main parts:

• deadLetterTargetArn: The ARN of the dead letter queue.
• maxReceiveCount: The number of times a message can be received before moving to the DLQ.

This policy is set as a JSON string when creating or updating the main queue.

json

{
  "RedrivePolicy": "{\"deadLetterTargetArn\": \"arn:aws:sqs:region:account-id:dead-letter-queue-name\", \"maxReceiveCount\": 5}"
}

Example

This example shows how to create a dead letter queue and a main queue with the dead letter queue configured using AWS CLI commands.

bash

# Create the dead letter queue
aws sqs create-queue --queue-name MyDeadLetterQueue

# Get the ARN of the dead letter queue
DLQ_ARN=$(aws sqs get-queue-attributes --queue-url https://sqs.region.amazonaws.com/account-id/MyDeadLetterQueue --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

# Create the main queue with RedrivePolicy pointing to the DLQ
aws sqs create-queue --queue-name MyMainQueue --attributes RedrivePolicy="{\"deadLetterTargetArn\":\"$DLQ_ARN\",\"maxReceiveCount\":3}"

# Verify the main queue attributes
aws sqs get-queue-attributes --queue-url https://sqs.region.amazonaws.com/account-id/MyMainQueue --attribute-names RedrivePolicy

Output

{
    "Attributes": {
        "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:region:account-id:MyDeadLetterQueue\",\"maxReceiveCount\":3}"
    }
}

Common Pitfalls

• Incorrect ARN: Using the wrong ARN for the dead letter queue will cause the redrive policy to fail.
• Missing permissions: The main queue must have permission to send messages to the DLQ.
• Low maxReceiveCount: Setting maxReceiveCount too low can move messages to DLQ prematurely.
• Not creating DLQ first: You must create the dead letter queue before referencing it in the main queue.

bash

Wrong way:
aws sqs create-queue --queue-name MainQueue --attributes RedrivePolicy="{\"deadLetterTargetArn\":\"arn:aws:sqs:region:account-id:WrongDLQ\",\"maxReceiveCount\":3}"

Right way:
# Create DLQ first
aws sqs create-queue --queue-name CorrectDLQ
DLQ_ARN=$(aws sqs get-queue-attributes --queue-url https://sqs.region.amazonaws.com/account-id/CorrectDLQ --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

# Then create main queue with correct ARN
aws sqs create-queue --queue-name MainQueue --attributes RedrivePolicy="{\"deadLetterTargetArn\":\"$DLQ_ARN\",\"maxReceiveCount\":3}"

Quick Reference

Dead Letter Queue Setup Tips:

• Create the DLQ queue first.
• Use the DLQ ARN in the RedrivePolicy of the main queue.
• Set maxReceiveCount based on your retry needs (commonly 3-5).
• Ensure permissions allow the main queue to send messages to the DLQ.

Key Takeaways

Create the dead letter queue before configuring it in the main queue.

Set the RedrivePolicy with the DLQ ARN and a suitable maxReceiveCount.

Ensure the main queue has permission to send messages to the DLQ.

Use the DLQ to isolate messages that fail processing after retries.

Test your setup by sending messages that fail to confirm DLQ behavior.