Dead letter queues in AWS - Commands & Configuration

Introduction

Sometimes messages sent to a queue cannot be processed correctly. Dead letter queues help by storing these problem messages separately so they can be checked and fixed later.

When your application receives messages that cause errors and you want to keep them for later review.

When you want to avoid losing messages that fail processing multiple times.

When you want to monitor and analyze why some messages fail in your queue system.

When you want to separate bad messages from good ones to keep your main queue clean.

When you want to retry processing failed messages after fixing the underlying issue.

Config File - main.tf

main.tf

provider "aws" {
  region = "us-east-1"
}

resource "aws_sqs_queue" "dlq_queue" {
  name = "example-dlq-queue"
}

resource "aws_sqs_queue" "main_queue" {
  name           = "example-main-queue"
  redrive_policy = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.dlq_queue.arn
    maxReceiveCount     = 3
  })
}

This Terraform file creates two AWS SQS queues:

• example-main-queue: The main queue where messages are sent.
• example-dlq-queue: The dead letter queue that stores messages that fail processing.

The redrive_policy on the main queue tells AWS to move messages to the dead letter queue after 3 failed processing attempts.

Commands

This command initializes Terraform in the current directory, downloading necessary plugins and preparing to create resources.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding latest version of hashicorp/aws...

- Installing hashicorp/aws v4.0.0...

- Installed hashicorp/aws v4.0.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure.

This command creates the AWS SQS queues as defined in the Terraform file without asking for confirmation.

Terminal

terraform apply -auto-approve

Expected Output

aws_sqs_queue.dlq_queue: Creating...

aws_sqs_queue.dlq_queue: Creation complete after 2s [id=https://sqs.us-east-1.amazonaws.com/123456789012/example-dlq-queue]

aws_sqs_queue.main_queue: Creating...

aws_sqs_queue.main_queue: Creation complete after 2s [id=https://sqs.us-east-1.amazonaws.com/123456789012/example-main-queue]



Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

→

-auto-approve - Skip interactive approval before applying changes

This command checks the redrive policy of the main queue to confirm it is linked to the dead letter queue.

Terminal

aws sqs get-queue-attributes --queue-url https://sqs.us-east-1.amazonaws.com/123456789012/example-main-queue --attribute-names RedrivePolicy

Expected Output

{

    "Attributes": {

        "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:123456789012:example-dlq-queue\",\"maxReceiveCount\":3}"

    }

}

→

--queue-url - Specifies the URL of the queue to check

→

--attribute-names - Specifies which attributes to retrieve

This command lists all SQS queues in your AWS account to verify both main and dead letter queues exist.

Terminal

aws sqs list-queues

Expected Output

{

    "QueueUrls": [

        "https://sqs.us-east-1.amazonaws.com/123456789012/example-main-queue",

        "https://sqs.us-east-1.amazonaws.com/123456789012/example-dlq-queue"

    ]

}

Key Concept

If a message fails processing multiple times, it moves automatically to the dead letter queue for later inspection.

Common Mistakes

Not setting the redrive policy on the main queue.

Without the redrive policy, messages will never move to the dead letter queue, so failed messages get lost or block processing.

Always configure the redrive policy with the dead letter queue ARN and maxReceiveCount on the main queue.

Using the wrong ARN or queue URL in the redrive policy.

If the ARN is incorrect, AWS cannot move messages to the dead letter queue, causing errors or message loss.

Copy the exact ARN of the dead letter queue and use it in the redrive policy.

Setting maxReceiveCount too high or too low without testing.

Too low causes messages to move to DLQ too quickly; too high delays error detection.

Choose a reasonable maxReceiveCount like 3 to balance retries and error handling.

Summary

Create a dead letter queue and a main queue with a redrive policy linking them.

Use Terraform to define and deploy these queues in AWS.

Verify the redrive policy and queue existence with AWS CLI commands.