{"id":8863,"library":"aws-cdk-aws-sqs","title":"AWS CDK SQS","description":"The `aws-cdk-aws-sqs` library provides AWS Cloud Development Kit (CDK) constructs for defining Amazon SQS (Simple Queue Service) resources in your AWS infrastructure as code. As part of the AWS CDK v1 ecosystem, it allows developers to programmatically create and configure SQS queues, dead-letter queues, and related settings using familiar programming languages. The AWS CDK project releases frequently, often with minor version updates every few weeks for both v1 and v2 lines.","status":"active","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","sqs","infrastructure-as-code","cloud","queue"],"install":[{"cmd":"pip install aws-cdk-aws-sqs","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"Core CDK library for application and stack definitions.","package":"aws-cdk.core","optional":false},{"reason":"Base class for all constructs in the CDK framework.","package":"constructs","optional":false},{"reason":"Used for cross-language interoperability in CDK.","package":"jsii","optional":false}],"imports":[{"note":"While technically functional, the idiomatic AWS CDK v1 pattern is to import submodules as aliases (e.g., `aws_sqs as sqs`) to maintain consistent namespace access across CDK modules and avoid direct symbol imports that can lead to clashes.","wrong":"from aws_cdk.aws_sqs import Queue","symbol":"Queue","correct":"from aws_cdk import aws_sqs as sqs"},{"note":"Duration is part of the core CDK library and is commonly accessed via the 'cdk' alias (e.g., `cdk.Duration`).","symbol":"Duration","correct":"import aws_cdk as cdk"}],"quickstart":{"code":"import aws_cdk as cdk\nimport aws_cdk.aws_sqs as sqs\nimport os\n\nclass MySqsStack(cdk.Stack):\n    def __init__(self, scope: cdk.App, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Define an SQS Queue\n        queue = sqs.Queue(\n            self, \"MySimpleQueue\",\n            visibility_timeout=cdk.Duration.seconds(300),\n            queue_name=\"MyApplicationQueue\" # Optional: give it a specific name\n        )\n\n        # Output the queue URL\n        cdk.CfnOutput(\n            self, \"QueueUrl\",\n            value=queue.queue_url,\n            description=\"The URL of the SQS queue\",\n        )\n\n# For authentication, CDK usually relies on AWS CLI configuration \n# or environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION).\n# No explicit auth needed in code for basic synth.\napp = cdk.App()\nMySqsStack(app, \"MySqsQueueStack\",\n            env=cdk.Environment(\n                account=os.environ.get(\"CDK_DEFAULT_ACCOUNT\"),\n                region=os.environ.get(\"CDK_DEFAULT_REGION\")\n            )\n        )\napp.synth()","lang":"python","description":"This quickstart demonstrates how to define a basic Amazon SQS queue using the `aws-cdk-aws-sqs` library. It creates an `App` and a `Stack`, then instantiates an `sqs.Queue` with a specified visibility timeout and outputs its URL. Ensure your AWS credentials are configured in your environment or `~/.aws/credentials` for successful deployment (`cdk deploy`)."},"warnings":[{"fix":"Refer to the official AWS CDK v1 to v2 migration guide. Key changes include importing `from aws_cdk_lib import aws_sqs as sqs` instead of `from aws_cdk import aws_sqs as sqs`, and installing `aws-cdk-lib` and `constructs` instead of individual `aws-cdk.aws-*` packages.","message":"Migrating from AWS CDK v1 (`aws-cdk-aws-sqs`) to v2 (`aws-cdk-lib.aws_sqs`) involves significant breaking changes, primarily around import paths and package structure. V2 consolidates all constructs into a single `aws-cdk-lib` package.","severity":"breaking","affected_versions":"Users moving from v1.x to v2.x"},{"fix":"Set `encryption=sqs.QueueEncryption.KMS` and provide a `kms_master_key` (e.g., an `aws_kms.Key` construct or an imported key) to the `Queue` properties.","message":"By default, SQS queues are encrypted with SQS-managed server-side encryption. If you require AWS KMS encryption with your own customer-managed key (CMK), you must explicitly configure the `encryption` and `encryption_master_key` properties.","severity":"gotcha","affected_versions":"All v1.x"},{"fix":"Define a separate `sqs.Queue` for the DLQ and configure the main queue's `dead_letter_queue` property, specifying the target queue and `max_receive_count`.","message":"Missing or misconfigured Dead-Letter Queues (DLQs) can lead to lost messages when message processing fails repeatedly. While optional, it's highly recommended for production queues.","severity":"gotcha","affected_versions":"All v1.x"},{"fix":"Use the `queue_name='MySpecificQueueName'` property when creating the `sqs.Queue` construct. Be cautious of naming collisions in the same AWS account/region.","message":"CDK automatically generates unique physical names for resources. If you need a specific, fixed queue name, set the `queue_name` property, but be aware of potential naming conflicts when deploying multiple instances or in shared accounts.","severity":"gotcha","affected_versions":"All v1.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Empty the SQS queue (and its associated DLQ if present) manually before attempting to destroy the stack again. For production, consider retaining queues or configuring deletion policies (`removal_policy=cdk.RemovalPolicy.RETAIN`) to avoid data loss.","cause":"Attempting to `cdk destroy` a stack that contains SQS queues with messages still in them, or a queue that is configured with a dead-letter queue that also contains messages.","error":"jsii.errors.JavaScriptError: Error: There are still resources remaining in the stack 'MySqsQueueStack'."},{"fix":"Define a separate SQS queue (e.g., `sqs.Queue(self, 'MyDLQ')`) and assign it as the `dead_letter_queue` to your main queue, also specifying `max_receive_count` for retry logic, e.g., `dead_letter_queue={ 'queue': my_dlq, 'max_receive_count': 3 }`.","cause":"This is a warning during CDK synthesis (not a deployment error) indicating that a best practice for message durability and error handling has not been followed.","error":"jsii.errors.JavaScriptError: 'MyQueue' has no associated Dead-Letter Queue (DLQ). Messages that fail to process will be lost."},{"fix":"Ensure you are using the correct attribute name, which is `queue.queue_arn` (or `queue.queue_url`). These properties are typically resolved during synthesis, so direct access within the stack definition usually works as expected. If passing across stacks, ensure appropriate methods like `export_value` are used.","cause":"This error typically indicates a typo in accessing the attribute, or attempting to access a property that only becomes available after synthesis or specific context.","error":"AttributeError: 'Queue' object has no attribute 'queue_arn'"}]}