Using dead-letter queues in Amazon SQS - Amazon SDK for JavaScript
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

The Amazon SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the Amazon SDK for JavaScript version 3 (V3).

Starting October 1, 2022, Amazon SDK for JavaScript (v3) will end support for Internet Explorer 11 (IE 11). For details, see Announcing the end of support for Internet Explorer 11 in the Amazon SDK for JavaScript (v3).

Using dead-letter queues in Amazon SQS

JavaScript code example that applies to Node.js execution

This Node.js code example shows:

  • How to use a queue to receive and hold messages from other queues that the queues can't process.

The scenario

A dead-letter queue is one that other (source) queues can target for messages that can't be processed successfully. You can set aside and isolate these messages in the dead-letter queue to determine why their processing did not succeed. You must individually configure each source queue that sends messages to a dead-letter queue. Multiple queues can target a single dead-letter queue.

In this example, a Node.js module is used to route messages to a dead letter queue. The Node.js module uses the SDK for JavaScript to use dead letter queues using this method of the SQS client class:

For more information about Amazon SQS dead-letter queues, see Using Amazon SQS dead-letter queues in the Amazon Simple Queue Service Developer Guide.

Prerequisite tasks

To set up and run this example, you must first complete these tasks:


These examples demonstrate how to import/export client service objects and command using ECMAScript6 (ES6).

Configuring source queues

After you create a queue to act as a dead-letter queue, you must configure the other queues that route unprocessed messages to the dead-letter queue. To do this, specify a redrive policy that identifies the queue to use as a dead-letter queue and the maximum number of receives by individual messages before they are routed to the dead-letter queue.

Create a libs directory, and create a Node.js module with the file name sqsClient.js. Copy and paste the code below into it, which creates the Amazon SQS client object. Replace REGION with your Amazon Region.

import { SQSClient } from "@aws-sdk/client-sqs"; // Set the AWS Region. const REGION = "REGION"; //e.g. "us-east-1" // Create SQS service object. const sqsClient = new SQSClient({ region: REGION }); export { sqsClient };

This example code can be found here on GitHub.

Create a Node.js module with the file name sqs_deadletterqueue.js. Be sure to configure the SDK as previously shown, including downloading the required clients and packages. Create a JSON object containing the parameters needed to update queue attributes, including the RedrivePolicy parameter that specifies both the ARN of the dead-letter queue, as well as the value of maxReceiveCount. Also specify the URL source queue you want to configure. Call the SetQueueAttributesCommand method.


Replace SQS_QUEUE_URL with the URL of the SQS queue, and DEAD_LETTER_QUEUE_ARN with the ARN of the dead letter queue.

// Import required AWS SDK clients and commands for Node.js import { SetQueueAttributesCommand } from "@aws-sdk/client-sqs"; import { sqsClient } from "./libs/sqsClient.js"; // Set the parameters var params = { Attributes: { RedrivePolicy: '{"deadLetterTargetArn":"DEAD_LETTER_QUEUE_ARN",' + '"maxReceiveCount":"10"}', //DEAD_LETTER_QUEUE_ARN }, QueueUrl: "SQS_QUEUE_URL", //SQS_QUEUE_URL }; const run = async () => { try { const data = await sqsClient.send(new SetQueueAttributesCommand(params)); console.log("Success", data); return data; // For unit tests. } catch (err) { console.log("Error", err); } }; run();

To run the example, enter the following at the command prompt.

node sqs_deadletterqueue.js // If you prefer JavaScript, enter 'sqs_deadletterqueue.js'

This example code can be found here on GitHub.