How to Use Dead Letter Queue with AWS Lambda

To use a dead letter queue (DLQ) with AWS Lambda, configure your Lambda function to send failed event messages to an Amazon SQS queue or SNS topic. This setup captures events that the Lambda function cannot process after retries, allowing you to inspect and handle failures separately.

Syntax

When configuring a Lambda function, you specify the dead letter queue using the DeadLetterConfig property. This property requires the ARN (Amazon Resource Name) of an SQS queue or SNS topic where failed events will be sent.

Key parts:

• DeadLetterConfig: The configuration block for the DLQ.
• TargetArn: The ARN of the SQS queue or SNS topic.

yaml

DeadLetterConfig:
  TargetArn: arn:aws:sqs:region:account-id:queue-name

Example

This example shows how to create a Lambda function with a dead letter queue using AWS CloudFormation YAML. The DLQ is an SQS queue that receives failed events after Lambda retries fail.

yaml

Resources:
  MyDeadLetterQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: my-lambda-dlq

  MyLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: my-function
      Handler: index.handler
      Runtime: nodejs18.x
      Role: arn:aws:iam::123456789012:role/lambda-execution-role
      Code:
        ZipFile: |
          exports.handler = async (event) => {
            throw new Error('Simulated failure');
          };
      DeadLetterConfig:
        TargetArn: !GetAtt MyDeadLetterQueue.Arn

Common Pitfalls

• Not setting permissions: The Lambda execution role must have permission to send messages to the DLQ (SQS or SNS).
• Using the wrong ARN: The TargetArn must be the full ARN of the SQS queue or SNS topic, not just the name.
• Expecting DLQ for synchronous invocations: DLQs only work for asynchronous Lambda invocations.
• Ignoring message retention: SQS queues have retention periods; expired messages are lost if not processed.

yaml

Wrong example (missing permissions):

Resources:
  MyDeadLetterQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: my-lambda-dlq

  MyLambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: my-function
      Handler: index.handler
      Runtime: nodejs18.x
      Role: arn:aws:iam::123456789012:role/lambda-execution-role
      Code:
        ZipFile: |
          exports.handler = async (event) => {
            throw new Error('Fail');
          };
      DeadLetterConfig:
        TargetArn: !GetAtt MyDeadLetterQueue.Arn

# Fix: Add permission to role to send messages to SQS queue.

Quick Reference

Dead Letter Queue Setup Tips:

• Use SQS or SNS as DLQ targets.
• Ensure Lambda execution role has sqs:SendMessage or sns:Publish permissions.
• DLQ only works for asynchronous Lambda invocations.
• Monitor DLQ for failed events and process them accordingly.

Key Takeaways

Configure the Lambda function's DeadLetterConfig with the ARN of an SQS queue or SNS topic to capture failed events.

Ensure the Lambda execution role has permission to send messages to the DLQ target.

Dead letter queues only work for asynchronous Lambda invocations, not synchronous ones.

Monitor and process messages in the DLQ to handle failures effectively.

Use proper ARNs and verify message retention settings on the DLQ.