# Using dead-letter queues in Amazon SQS Dead-letter queues Amazon SQS supports dead-letter queues (DLQs), which source queues can target for messages that are not processed successfully. DLQs are useful for debugging your application because you can isolate unconsumed messages to determine why processing did not succeed. For optimal performance, it is a best practice to keep the source queue and DLQ within the same AWS account and Region. Once messages are in a dead-letter queue, you can: + Examine logs for exceptions that might have caused messages to be moved to a dead-letter queue. + Analyze the contents of messages moved to the dead-letter queue to diagnose application issues. + Determine whether you have given your consumer sufficient time to process messages. + Move messages out of the dead-letter queue using [dead-letter queue redrive](sqs-configure-dead-letter-queue.md). You must first create a new queue before configuring it as a dead-letter queue. For information about configuring a dead-letter queue using the Amazon SQS console, see [Configure a dead-letter queue using the Amazon SQS console](sqs-configure-dead-letter-queue.md). For help with dead-letter queues, such as how to configure an alarm for any messages moved to a dead-letter queue, see [Creating alarms for dead-letter queues using Amazon CloudWatch](dead-letter-queues-alarms-cloudwatch.md). **Note** Don't use a dead-letter queue with a FIFO queue if you don't want to break the exact order of messages or operations. For example, don't use a dead-letter queue with instructions in an Edit Decision List (EDL) for a video editing suite, where changing the order of edits changes the context of subsequent edits. ## Using policies for dead-letter queues Use a **redrive policy** to specify the `maxReceiveCount`. The `maxReceiveCount` is the number of times a consumer can receive a message from a source queue before it is moved to a dead-letter queue. For example, if the `maxReceiveCount` is set to a low value such as 1, one failure to receive a message would cause the message to move to the dead-letter queue. To ensure that your system is resilient against errors, set the `maxReceiveCount` high enough to allow for sufficient retries. For standard queues with a redrive policy where `maxReceiveCount` is greater than 3, if a message is received 3 or more times without being deleted, SQS moves it to the back of the queue. The `ApproximateAgeOfOldestMessage` metric then reflects the age of the next message that hasn’t exceeded this threshold. The **redrive allow policy** specifies which source queues can access the dead-letter queue. You can choose whether to allow all source queues, allow specific source queues, or deny all source queues use of the dead-letter queue. The default allows all source queues to use the dead-letter queue. If you choose to allow specific queues using the `byQueue` option, you can specify up to 10 source queues using the source queue Amazon Resource Name (ARN). If you specify `denyAll`, the queue cannot be used as a dead-letter queue. ## Understanding message retention periods for dead-letter queues For standard queues, the expiration of a message is always based on its original enqueue timestamp. When a message is moved to a dead-letter queue, the enqueue timestamp is unchanged. The `ApproximateAgeOfOldestMessage` metric indicates when the message moved to the dead-letter queue, not when the message was originally sent. For example, assume that a message spends 1 day in the original queue before it's moved to a dead-letter queue. If the dead-letter queue's retention period is 4 days, the message is deleted from the dead-letter queue after 3 days and the `ApproximateAgeOfOldestMessage` is 3 days. Thus, it is a best practice to always set the retention period of a dead-letter queue to be longer than the retention period of the original queue. For FIFO queues, the enqueue timestamp resets when the message is moved to a dead-letter queue. The `ApproximateAgeOfOldestMessage` metric indicates when the message moved to the dead-letter queue. In the same example above, the message is deleted from the dead-letter queue after four days and the `ApproximateAgeOfOldestMessage` is four days. # Configure a dead-letter queue using the Amazon SQS console Configuring a dead-letter queue A dead-letter queue (DLQ) is a queue that receives messages that were not successfully processed from another queue, known as the source queue. Amazon SQS does *not* create the dead-letter queue automatically. You must first create the queue before using it as a dead-letter queue. When configuring a DLQ, the queue type must match the source queue type—a [FIFO queue](sqs-fifo-queues.md) can only use a FIFO DLQ, and a [standard queue](standard-queues.md) can only use a standard DLQ. You can configure a dead-letter queue when you create or edit a queue. For more details, see [Using dead-letter queues in Amazon SQS](sqs-dead-letter-queues.md). **To configure a dead-letter queue for an existing queue (console)** 1. Open the Amazon SQS console at [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/). 1. In the navigation pane, choose **Queues**. 1. Select the **source queue** (the queue that will send failed messages to the dead-letter queue), then choose **Edit**. 1. Scroll to the **Dead-letter queue** section and toggle **Enabled**. 1. Under **Dead-letter queue settings**, choose the Amazon Resource Name (ARN) of an existing queue that you want to use as the **dead-letter queue**. 1. Set the **Maximum receives** value, which defines how many times a message can be received before being sent to the dead-letter queue (valid range: **1 to 1,000**). 1. Choose **Save**. # Learn how to configure a dead-letter queue redrive in Amazon SQS Configuring a dead-letter queue redrive Use dead-letter queue redrive to move unconsumed messages from a dead-letter queue to another destination for processing. By default, dead-letter queue redrive moves messages from a dead-letter queue to a source queue. However, you can also configure any other queue as the redrive destination if both queues are the same type. For example, if the dead-letter queue is a FIFO queue, the redrive destination queue must be a FIFO queue as well. Additionally, you can configure the redrive velocity to set the rate at which Amazon SQS moves messages. **Note** When a message is moved from a FIFO queue to a FIFO DLQ, the original message's deduplication ID will be replaced with the original message's ID. This is to make sure that the DLQ deduplication will not prevent storing of two independent messages that happen to share a deduplication ID. Dead-letter queues redrive messages in the order they are received, starting with the oldest message. However, the destination queue ingests the redriven messages, as well as new messages from other producers, according to the order in which it receives them. For example, if a producer is sending messages to a source FIFO queue when simultaneously receiving redriven messages from a dead letter queue, the redriven messages will interweave with the new messages from the producer. **Note** The redrive task resets the retention period. All redriven messages are considered new messages with a new `messageID` and `enqueueTime` are assigned to redriven messages. ## Configuring a dead-letter queue redrive for an existing standard queue using the Amazon SQS API You can configure a dead-letter queue redrive using the `StartMessageMoveTask`, `ListMessageMoveTasks`, and `CancelMessageMoveTask` API actions: | API action | Description | | --- | --- | | [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_StartMessageMoveTask.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_StartMessageMoveTask.html) | Starts an asynchronous task to move messages from a specified source queue to a specified destination queue. | | [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ListMessageMoveTasks.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ListMessageMoveTasks.html) | Gets the most recent message movement tasks (up to 10) under a specific source queue. | | [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CancelMessageMoveTask.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CancelMessageMoveTask.html) | Cancels a specified message movement task. A message movement can only be cancelled when the current status is RUNNING. | ## Configuring a dead-letter queue redrive for an existing standard queue using the Amazon SQS console 1. Open the Amazon SQS console at [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/). 1. In the navigation pane, choose **Queues**. 1. Choose the name of queue that you have configured as a [dead-letter queue](sqs-configure-dead-letter-queue.md). 1. Choose **Start DLQ redrive**. 1. Under **Redrive configuration**, for **Message destination**, do either of the following: + To redrive messages to their source queue, choose **Redrive to source queue(s)**. + To redrive messages to another queue, choose **Redrive to custom destination**. Then, enter the Amazon Resource Name (ARN) of an existing destination queue. 1. Under **Velocity control settings**, choose one of the following: + **System optimized** - Redrive dead-letter queue messages at the maximum number of messages per second. + **Custom max velocity** - Redrive dead-letter queue messages with a custom maximum rate of messages per second. The maximum allowed rate is 500 messages per second. + It is recommended to start with a small value for Custom max velocity and verify that the source queue doesn't get overwhelmed with messages. From there, gradually ramp-up the Custom max velocity value, continuing to monitor the state of the source queue. 1. When you finish configuring the dead-letter queue redrive, choose **Redrive messages**. **Important** Amazon SQS doesn't support filtering and modifying messages while redriving them from the dead-letter queue. A dead-letter queue redrive task can run a maximum of 36 hours. Amazon SQS supports a maximum of 100 active redrive tasks per account. 1. If you want to cancel the message redrive task, on the **Details** page for your queue, choose **Cancel DLQ redrive**. When canceling an in progress message redrive, any messages that have already been successfully moved to their move destination queue will remain in the destination queue. ## Configuring queue permissions for dead-letter queue redrive Configuring queue permissions for dead-letter queue redrive You can give user access to specific dead-letter queue actions by adding permissions to your policy. The minimum required permissions for a dead-letter queue redrive are as follows: | Minimum Permissions | Required API methods | | --- | --- | | To start a message redrive | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-dead-letter-queue-redrive.html) | | To cancel an in-progress message redrive | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-dead-letter-queue-redrive.html) | | To show a message move status | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-dead-letter-queue-redrive.html) | **To configure permissions for an encrypted queue pair (a source queue with a dead-letter queue)** Use the following steps to configure minimum permissions for a dead-letter queue (DLQ) redrive: 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, select **Policies**. 1. Create a new [https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) and add the following permissions. Attach the policy to the IAM [user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) or [role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that will perform the redrive operation. + Permissions for the DLQ (source queue): + `sqs:StartMessageMoveTask` + `sqs:CancelMessageMoveTask` + `sqs:ListMessageMoveTasks` + `sqs:ReceiveMessage` + `sqs:DeleteMessage` + `sqs:GetQueueAttributes` + `sqs:ListDeadLetterSourceQueues` + Specify the **Resource ARN** of the DLQ (source queue) (for example, "arn:aws:sqs:**:**:**"). + Permissions for destination queue: + `sqs:SendMessage` + Specify the `Resource ARN` of the destination queue (for example, "arn:aws:sqs:*::*"). + Permissions for KMS keys: + `kms:Decrypt` (Needed to decrypt messages in the DLQ.) + `kms:GenerateDataKey` (Needed to encrypt messages in the destination queue.) + `Resource` ARNs: + The ARN of the KMS key used to encrypt messages in the **DLQ** (source queue) (for example, "arn:aws:kms:**:**:key/**"). + The ARN of the KMS key used to encrypt messages in the **destination queue** (for example, "arn:aws:kms:**:**:key/**"). Your access policy should resemble the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:StartMessageMoveTask", "sqs:CancelMessageMoveTask", "sqs:ListMessageMoveTasks", "sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes", "sqs:ListDeadLetterSourceQueues" ], "Resource": "arn:aws:sqs:us-west-1:123456789012:", "Condition": { "StringEquals": { "aws:ResourceTag/QueueRole": "source" } } }, { "Effect": "Allow", "Action": "sqs:SendMessage", "Resource": "arn:aws:sqs:us-west-1:123456789012:", "Condition": { "StringEquals": { "aws:ResourceTag/QueueRole": "destination" } } }, { "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": [ "arn:aws:kms:us-west-1:123456789012:key/", "arn:aws:kms:us-west-1:123456789012:key/" ] } ] } ``` ------ **To configure permissions using a non-encrypted queue pair (a source queue with a dead-letter queue)** Follow these steps to configure the minimum permissions required for handling a standard, **unencrypted** dead-letter queue (DLQ). Required minimum permissions are to *receive*, *delete* and *get* attributes from the dead-letter queue, and *send* attributes to the source queue. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, select **Policies**. 1. Create a new [https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) and add the following permissions. Attach the policy to the IAM [user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) or [role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that will perform the redrive operation. + Permissions for the DLQ (source queue): + `sqs:StartMessageMoveTask` + `sqs:CancelMessageMoveTask` + `sqs:ListMessageMoveTasks` + `sqs:ReceiveMessage` + `sqs:DeleteMessage` + `sqs:ListDeadLetterSourceQueues` + Specify the **Resource ARN** of the DLQ (source queue) (for example, "arn:aws:sqs:**:**:**"). + Permissions for destination queue: + `sqs:SendMessage` + Specify the `Resource ARN` of the destination queue (for example, "arn:aws:sqs:*::*"). Your access policy should resemble the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:StartMessageMoveTask", "sqs:CancelMessageMoveTask", "sqs:ListMessageMoveTasks", "sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes", "sqs:ListDeadLetterSourceQueues" ], "Resource": "arn:aws:sqs:us-west-1:111122223333:", "Condition": { "StringEquals": { "aws:ResourceTag/QueueRole": "source" } } }, { "Effect": "Allow", "Action": "sqs:SendMessage", "Resource": "arn:aws:sqs:us-west-1:111122223333:", "Condition": { "StringEquals": { "aws:ResourceTag/QueueRole": "destination" } } } ] } ``` ------ ## Using dead-letter queue redrive with VPC endpoint access control When you restrict queue access to specific VPCs using the `aws:sourceVpc` condition, you need to make an exception for AWS services to enable dead-letter queue (DLQ) redrive functionality. This is because the Amazon SQS service operates outside your VPC when moving messages. To allow DLQ redrive operations, add the `aws:CalledViaLast` condition to your queue policy. This allows Amazon SQS to make API calls on your behalf while maintaining VPC restrictions for direct access. To allow both VPC-restricted access and DLQ redrive: 1. Use the `aws:CalledViaLast` condition in your queue policy. 1. Apply the policy to both the source queue and the DLQ 1. Maintain VPC restrictions for direct access from other sources Here is an example policy that implements these requirements: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "SQSRedriveWithVpcRestriction", "Statement": [ { "Sid": "DenyOutsideVPCUnlessAWSService_DestQueue", "Effect": "Deny", "Principal": "*", "Action": "sqs:*", "Resource": "arn:aws:sqs:*:111122223333:DestQueue", "Condition": { "StringNotEquals": { "aws:SourceVpc": "vpc-1234567890abcdef0" }, "StringNotEqualsIfExists": { "aws:CalledViaLast": "sqs.amazonaws.com" } } }, { "Sid": "DenyOutsideVPCUnlessAWSService_DLQ", "Effect": "Deny", "Principal": "*", "Action": "sqs:*", "Resource": "arn:aws:sqs:*:111122223333:Dlq", "Condition": { "StringNotEquals": { "aws:SourceVpc": "vpc-1234567890abcdef0" }, "StringNotEqualsIfExists": { "aws:CalledViaLast": "sqs.amazonaws.com" } } } ] } ``` ------ + Replace the placeholder values with your actual values + This policy uses a "deny" statement with conditions, which is more secure than using "allow" statements + The `StringNotEqualsIfExists` operator handles cases where the condition key might not be present in the request context. Alternatively, you can use the `aws:ViaAWSService` condition key to allow service-based access while maintaining VPC restrictions. This condition key indicates whether the request comes from an AWS service. Here is an example policy that uses `aws:ViaAWSService` instead of `aws:CalledViaLast`: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "SQSRedriveWithVpcRestriction", "Statement": [ { "Sid": "DenyOutsideVPCUnlessAWSService_DestQueue", "Effect": "Deny", "Principal": "*", "Action": "sqs:*", "Resource": "arn:aws:sqs:*:111122223333:DestQueue", "Condition": { "StringNotEquals": { "aws:SourceVpc": "vpc-1234567890abcdef0" }, "BoolIfExists": { "aws:ViaAWSService": "false" } } }, { "Sid": "DenyOutsideVPCUnlessAWSService_DLQ", "Effect": "Deny", "Principal": "*", "Action": "sqs:*", "Resource": "arn:aws:sqs:*:111122223333:Dlq", "Condition": { "StringNotEquals": { "aws:SourceVpc": "vpc-1234567890abcdef0" }, "BoolIfExists": { "aws:ViaAWSService": "false" } } } ] } ``` ------ The BoolIfExists operator with `aws:ViaAWSService` condition ensures that requests are allowed when they come from services while maintaining VPC restrictions for direct access. This can be simpler to understand and maintain, as it directly checks if the request is made by an AWS service rather than checking which service made the last call. For more information on condition keys used in IAM and resource policies, see IAM JSON policy elements: Condition. # CloudTrail update and permission requirements for Amazon SQS dead-letter queue redrive CloudTrail update and permission requirements On June 8, 2023, Amazon SQS introduced dead-letter queue (DLQ) redrive for AWS SDK and AWS Command Line Interface (CLI). This capability is an addition to the already supported DLQ redrive for the AWS console. If you've previously used the AWS console to redrive dead-letter queue messages, you may be affected by the following changes: ## CloudTrail event renaming On October 15, 2023, the CloudTrail event names for dead-letter queue redrive will change on the Amazon SQS console. If you've set alarms for these CloudTrail events, you must update them now. The following are the new CloudTrail event names for DLQ redrive: | Previous event name | New event name | | --- | --- | | `CreateMoveTask` | `StartMessageMoveTask` | | `CancelMoveTask` | `CancelMessageMoveTask` | ## Updated permissions Included with the SDK and CLI release, Amazon SQS has also updated queue permissions for DLQ redrive to adhere to security best practices. Use the following queue permission types to redrive messages from your DLQs. 1. Action-based permissions (update for the DLQ API actions) 1. Managed Amazon SQS policy permissions 1. Permission policy that uses sqs:\$1 wildcard **Important** To use the DLQ redrive for SDK or CLI, you are required to have a DLQ redrive permission policy that matches one of the above options. If your queue permissions for DLQ redrive don't match one of the options above, you must update your permissions by August 31, 2023. Between now and August 31, 2023, your account will be able to redrive messages using the permissions you configured using the AWS console only in the regions where you have previously used the DLQ redrive. For example, say you had "Account A" in both us-east-1 and eu-west-1. "Account A" was used to redrive messages on the AWS console in us-east-1 prior to June 8, 2023, but not in eu-west-1. Between June 8, 2023 and August 31, 2023, if "Account A’s" policy permissions don't match one of the options above, it can only be used to redrive messages on the AWS console in us-east-1, and not in eu-west-1. **Important** If your DLQ redrive permissions do not match one of these options after August 31, 2023, your account will no longer be able to redrive DLQ messages using the AWS console. However, if you used the DLQ redrive feature on the AWS Console during August 2023, you have an extension until October 15, 2023 to adopt the new permissions according to one of these options. For more information, see [Identifying impacted policies](#identifying-impacted-policies). The following are queue permission examples for each DLQ redrive option. When using [server-side encrypted (SSE) queues](sqs-configure-sse-existing-queue.md), the corresponding AWS KMS key permission is required. **Action-based** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes", "sqs:StartMessageMoveTask", "sqs:ListMessageMoveTasks", "sqs:CancelMessageMoveTask" ], "Resource": "arn:aws:sqs:us-west-1:123456789012:" }, { "Effect": "Allow", "Action": "sqs:SendMessage", "Resource": "arn:aws:sqs:us-west-1:123456789012:" } ] } ``` ------ **Managed policy** The following managed policies contain the required updated permissions: + **AmazonSQSFullAccess** – Includes the following dead-letter queue redrive tasks: start, cancel, and list. + **AmazonSQSReadOnlyAccess** – Provides read-only access, and includes the list dead-letter queue redrive task. ![\[Amazon SQS showing the permission policy AmazonSQSFullAccess to start, cancel and list tasks for dead-letter queue redrive tasks, and AmazonSQSReadOnlyAccess for read-only access.\]](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/images/sqs-dlq-cloudtrail.png) **Permission Policy that uses sqs\$1 wildcard** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sqs:*", "Resource": "*" } ] } ``` ------ ## Identifying impacted policies If you are using customer managed policies (CMPs), you can use AWS CloudTrail and IAM to identify the policies impacted by the queue permissions update. **Note** If you are using `AmazonSQSFullAccess` and `AmazonSQSReadOnlyAccess`, no further action is required. 1. Sign in to the AWS CloudTrail console. 1. On the **Event history** page, under **Look up attributes**, use the drop down menu to select *Event name*. Then, search for `CreateMoveTask`. 1. Choose an event to open the **Details** page. In the **Event records** section, retrieve the `UserName` or `RoleName` from the `userIdentity` ARN. 1. Sign into IAM console. + For users, choose Users. Select the user with the `UserName` identified in the previous step. + For roles, choose Roles. Search for the user with the `RoleName` identified in the previous step. 1. On the **Details** page, in the **Permissions** section, review any policies with the `sqs:` prefix in `Action`, or review policies that have Amazon SQS queue defined in `Resource`. # Creating alarms for dead-letter queues using Amazon CloudWatch Set up a CloudWatch alarm to monitor messages in a dead-letter queue using the [`ApproximateNumberOfMessagesVisible`](sqs-available-cloudwatch-metrics.md) metric. For detailed instructions, see [Creating CloudWatch alarms for Amazon SQS metrics](set-cloudwatch-alarms-for-metrics.md). When the alarm triggers, indicating messages have been moved to the dead-letter queue, you can [poll](sqs-short-and-long-polling.md) the queue to review and retrieve them.