How to Set Up an AWS SQS Dead-Letter Queue

The problem a DLQ solves

If a consumer can't process a message, SQS makes it visible again and the consumer retries it - forever. One "poison" message can block the queue and burn your consumer in a loop. A dead-letter queue (DLQ) is where SQS moves a message after it's failed too many times, so the main queue keeps flowing and you can inspect the bad ones separately.

The setup: a second queue + a redrive policy

# The DLQ - just a normal queue
resource "aws_sqs_queue" "dlq" {
  name = "orders-dlq"
}

# The main queue points failed messages at the DLQ
resource "aws_sqs_queue" "orders" {
  name = "orders"

  redrive_policy = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.dlq.arn
    maxReceiveCount     = 3      # after 3 failed receives -> DLQ
  })
}

• deadLetterTargetArn - which queue to send failed messages to.
• maxReceiveCount - how many times a message can be received (and not deleted) before SQS moves it to the DLQ. 3-5 is typical.

How it behaves

1. Consumer receives a message, fails, doesn't delete it.
2. After the visibility timeout it reappears; repeat up to maxReceiveCount.
3. On the next failure past the limit, SQS moves it to orders-dlq automatically.

Now the main queue isn't stuck, and every poison message is parked in the DLQ.

Operating it

• Alarm on DLQ depth - a non-empty DLQ means something's broken; alert on ApproximateNumberOfMessagesVisible > 0.
• Inspect, fix, redrive - read the failed messages, fix the bug, then redrive them from the DLQ back to the main queue.
• Set a long retention on the DLQ (up to 14 days) so you don't lose evidence.