{"id":12064,"library":"sqs-consumer","title":"SQS Consumer for Node.js","description":"sqs-consumer is a robust JavaScript/TypeScript library designed to streamline the development of applications that process messages from Amazon SQS queues in Node.js environments. It significantly reduces common boilerplate by managing continuous polling, message visibility timeouts, automatic message deletion upon successful processing, and concurrent message handling. The current stable version, 14.2.6, reflects active development with frequent canary releases and stable updates primarily focused on maintenance, dependency management, and bug fixes. Its core differentiator is providing a high-level, event-driven abstraction over the AWS SQS API, which simplifies building scalable and resilient queue-based microservices compared to direct interactions with the lower-level `@aws-sdk/client-sqs`. The library is built for modern Node.js (>=20.0.0) and includes comprehensive TypeScript type definitions.","status":"active","version":"14.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/bbc/sqs-consumer","tags":["javascript","consumer","queue","sqs","typescript"],"install":[{"cmd":"npm install sqs-consumer","lang":"bash","label":"npm"},{"cmd":"yarn add sqs-consumer","lang":"bash","label":"yarn"},{"cmd":"pnpm add sqs-consumer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with the Amazon SQS service. The library is built on AWS SDK v3.","package":"@aws-sdk/client-sqs","optional":false}],"imports":[{"note":"The primary entry point is a named export `Consumer`, which is a factory function. CommonJS `require()` is not supported in recent major versions.","wrong":"import Consumer from 'sqs-consumer';\nconst Consumer = require('sqs-consumer');","symbol":"Consumer","correct":"import { Consumer } from 'sqs-consumer';"},{"note":"The library expects an instance of `SQSClient` from AWS SDK v3, not the older `aws-sdk` package (v2).","wrong":"import { SQS } from 'aws-sdk';","symbol":"SQSClient","correct":"import { SQSClient } from '@aws-sdk/client-sqs';"},{"note":"Type definition for configuring the SQS consumer, useful for TypeScript projects.","symbol":"ConsumerOptions","correct":"import { ConsumerOptions } from 'sqs-consumer';"},{"note":"The type definition for an SQS message, useful for typing the `handleMessage` callback.","symbol":"Message","correct":"import { Message } from '@aws-sdk/client-sqs';"}],"quickstart":{"code":"import { Consumer } from 'sqs-consumer';\nimport { SQSClient, Message } from '@aws-sdk/client-sqs';\n\n// Ensure environment variables are set for AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,\n// or pass credentials directly to SQSClient configuration.\nconst REGION = process.env.AWS_REGION ?? 'us-east-1';\nconst SQS_QUEUE_URL = process.env.SQS_QUEUE_URL ?? 'https://sqs.us-east-1.amazonaws.com/123456789012/my-test-queue';\n\nif (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) {\n  console.warn('AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) are not set in environment variables. Consumer may fail without proper authentication.');\n}\n\nconst sqs = new SQSClient({ region: REGION });\n\nconst app = Consumer.create({\n  queueUrl: SQS_QUEUE_URL,\n  handleMessage: async (message: Message) => {\n    // This function is called for each message received.\n    console.log(`Processing message: ${message.MessageId}`);\n    console.log(`Message Body: ${message.Body}`);\n\n    try {\n      const data = JSON.parse(message.Body ?? '{}');\n      console.log('Parsed data:', data);\n      // Simulate some asynchronous work.\n      await new Promise(resolve => setTimeout(resolve, Math.random() * 500));\n      console.log(`Successfully processed and acknowledged message ${message.MessageId}`);\n      // Returning nothing (or a fulfilled promise) implies successful processing and message deletion.\n    } catch (error) {\n      console.error(`Error processing message ${message.MessageId}:`, error);\n      // If handleMessage throws, the message will NOT be deleted and will return to the queue for retry.\n      throw error; // Re-throw to signal a processing failure.\n    }\n  },\n  sqs: sqs, // Pass the instantiated SQSClient\n  batchSize: 5, // Process up to 5 messages at once\n  visibilityTimeout: 30, // seconds\n  terminateVisibilityTimeout: true // Ensures messages are retried faster on processing_error\n});\n\napp.on('error', (err) => {\n  console.error('Consumer-level error (e.g., SQS polling issue):', err.message);\n});\n\napp.on('processing_error', (err, message) => {\n  console.error(`Handler error for message ${message.MessageId}:`, err.message);\n  // This event is fired when handleMessage throws an error.\n  // The message will not be deleted and will be retried (potentially immediately if terminateVisibilityTimeout is true).\n});\n\napp.on('timeout_exceeded', (message) => {\n  console.warn(`Message processing timed out for ${message.MessageId}.`);\n});\n\napp.on('empty', () => {\n  console.log('Queue is currently empty. Waiting for new messages...');\n});\n\napp.start();\nconsole.log('SQS Consumer started. Waiting for messages...');\n\n// Graceful shutdown on application exit signals\nprocess.on('SIGTERM', async () => {\n  console.log('SIGTERM received. Stopping consumer...');\n  await app.stop();\n  console.log('Consumer stopped. Exiting.');\n  process.exit(0);\n});\n\nprocess.on('SIGINT', async () => {\n  console.log('SIGINT received. Stopping consumer...');\n  await app.stop();\n  console.log('Consumer stopped. Exiting.');\n  process.exit(0);\n});","lang":"typescript","description":"This quickstart demonstrates how to create and start an SQS consumer using `sqs-consumer`, process messages asynchronously, handle errors during message processing, and implement graceful shutdown. It uses `SQSClient` from AWS SDK v3 and includes relevant event listeners."},"warnings":[{"fix":"Migrate your import statements from `const { Consumer } = require('sqs-consumer');` to `import { Consumer } from 'sqs-consumer';`.","message":"`sqs-consumer` transitioned to an ES Module (ESM) codebase and expects usage with `import` statements. Attempting to use CommonJS `require()` will result in import errors or `TypeError`s. This change typically aligns with versions that integrate AWS SDK v3.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Implement comprehensive `try...catch` blocks within `handleMessage` to explicitly manage errors. Consider setting `terminateVisibilityTimeout: true` in consumer options to make failed messages available sooner for retry. Always configure a Dead Letter Queue (DLQ) for your SQS queue to prevent poison messages from indefinitely re-appearing.","message":"Errors thrown within the `handleMessage` function are critical. If an `async handleMessage` function throws an error (or returns a rejected promise), the message will NOT be automatically deleted from the SQS queue. It will become visible again after its visibility timeout expires, potentially leading to infinite retries if not handled by a dead-letter queue (DLQ) policy. Ensure your `handleMessage` logic is robust or uses `terminateVisibilityTimeout`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that the IAM role or user associated with your application has the necessary SQS permissions attached. Use `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables or pass a pre-configured `SQSClient` instance with correct credentials and region.","message":"Incorrect AWS Identity and Access Management (IAM) permissions for the SQS queue will prevent the consumer from polling or deleting messages. Required permissions include `sqs:ReceiveMessage`, `sqs:DeleteMessage`, `sqs:DeleteMessageBatch`, `sqs:ChangeMessageVisibility`, `sqs:ChangeMessageVisibilityBatch`, `sqs:GetQueueAttributes`, and `sqs:GetQueueUrl`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `sqs-consumer@14.2.7` or later. Always wrap your `handleMessage` logic in a `try...catch` block to prevent exceptions from propagating and impacting the consumer's stability.","message":"Prior to version `14.2.7-canary.2`, a bug existed where unhandled errors within `handleMessage` could cause the entire consumer polling loop to crash, effectively stopping message processing entirely. While fixed in newer versions, it highlights the importance of robust error handling.","severity":"gotcha","affected_versions":"<14.2.7-canary.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables are set, or provide an `SQSClient` instance with credentials explicitly defined in the `Consumer.create` options.","cause":"The AWS SDK (used by sqs-consumer) cannot find AWS credentials in the environment, shared credential file, or passed SQSClient configuration.","error":"Error: Missing credentials in config"},{"fix":"Change your import statement to `import { Consumer } from 'sqs-consumer';` for ES Modules.","cause":"Attempting to import `Consumer` using a default import syntax (`import Consumer from 'sqs-consumer'`) or CommonJS `require()` when the package is an ES Module with named exports.","error":"TypeError: (0 , sqs_consumer_1.Consumer) is not a function"},{"fix":"Review and update the IAM policy attached to your AWS user or role, ensuring it includes required permissions like `sqs:ReceiveMessage`, `sqs:DeleteMessage`, and `sqs:ChangeMessageVisibility` for the target queue.","cause":"The AWS IAM principal (user or role) configured for the application lacks the necessary permissions to interact with the specified SQS queue.","error":"AccessDeniedException: User: arn:aws:iam::ACCOUNT_ID:user/IAM_USER is not authorized to perform: sqs:ReceiveMessage on resource: QUEUE_URL"},{"fix":"Double-check the `queueUrl` and `region` provided in the `Consumer.create` options. Ensure the SQS queue exists and its URL matches the configured value.","cause":"The `queueUrl` provided to `Consumer.create` is incorrect, or the queue does not exist in the specified AWS region.","error":"Consumer-level error (e.g., SQS polling issue): AWS.SimpleQueueService.QueueDoesNotExist: The specified queue does not exist for this wsdl version."}],"ecosystem":"npm"}