A Stacktape SQS queue is a fully managed, serverless message queue built on Amazon SQS. Producers send messages and consumers process them at their own pace — decoupling your services so a spike in one part of your system does not cascade into another. You pay per message with no upfront cost and no capacity to manage.
SQS uses pay-per-request pricing with no minimum fee. The first 1 million requests per month are included in the AWS Free Tier. After that, standard queues are cheaper than FIFO queues. Each 64 KB chunk of a message counts as one request. Long polling reduces costs by making fewer API calls.
When to use
Use an SQS queue when you need to decouple a producer from a consumer. Common scenarios:
- Background processing — a web API accepts a request, drops a message on a queue, and returns immediately while a Lambda function processes the work asynchronously.
- Task queues — distribute work items (image resizing, email sending, report generation) across consumers that process at their own pace.
- Buffering between services — absorb traffic bursts so a downstream service is not overwhelmed. The queue acts as a shock absorber between a fast producer and a slower consumer.
- Retry and dead-letter workflows — messages that fail processing are automatically retried and, after a configurable number of attempts, moved to a dead-letter queue for inspection.
When NOT to use
- Fan-out to multiple consumers — SQS is designed for one logical consumer workflow per message. Standard queues use at-least-once delivery, so a message can occasionally be delivered more than once; use an SNS topic or an EventBridge event bus when every service needs its own copy.
- Real-time streaming — for ordered, high-throughput data streams where consumers need to replay data, use a Kinesis stream.
- Request-response — SQS is one-way. If your caller needs a synchronous response, invoke the downstream service directly or use an HTTP API Gateway.
- Sub-second latency requirements — SQS standard queues have at-least-once delivery with occasional re-ordering. For strict real-time guarantees, consider direct invocation or WebSockets.
Basic example
The simplest SQS queue requires no properties at all. Stacktape creates a standard queue with sensible defaults: 256 KB max message size, 4-day retention, 30-second visibility timeout, and short polling.
Standard vs FIFO queues
Stacktape SQS queues support two queue types: standard (default) and FIFO. The choice affects ordering, throughput, and delivery guarantees.
| Standard | FIFO | |
|---|---|---|
| Ordering | Best-effort | Strict within each message group |
| Delivery | At-least-once (rare duplicates possible) | Exactly-once |
| Throughput | Nearly unlimited | ~300 msg/s (3,000 with batching), or ~70,000 with high-throughput mode |
| Use cases | Background jobs, notifications, buffering | Financial transactions, sequential workflows, event sourcing |
Standard queues are the right choice for most workloads. Use FIFO only when message ordering or exactly-once processing is a hard requirement, and you can accept lower throughput.
FIFO queue
Set fifoEnabled: true to create a FIFO queue. FIFO queues require deduplication — either enable contentBasedDeduplication (SQS uses a SHA-256 hash of the message body) or provide a MessageDeduplicationId on each message you send.
High-throughput FIFO
For FIFO queues that need higher throughput, set fifoHighThroughput: true. This enables up to ~70,000 messages per second per queue by partitioning messages by MessageGroupId. Order is guaranteed within each message group but not across groups. This mode requires fifoEnabled: true.
Dead-letter queues
A dead-letter queue (DLQ) catches messages that fail processing after a configurable number of attempts. Without a DLQ, a "poison" message — one that always causes a processing error — blocks the queue indefinitely because it keeps becoming visible and being retried. With a DLQ, the message moves aside after maxReceiveCount failures so you can inspect and reprocess it later.
Configure redrivePolicy to route failed messages to a DLQ. Use targetSqsQueueName for another queue in the same Stacktape config, or targetSqsQueueArn for an external queue. A typical starting value for maxReceiveCount is 3–5: lower for fast-failing workloads, higher when transient errors are common.
Polling and visibility
Two properties control how consumers interact with the queue:
Long polling (longPollingSeconds) determines how long the queue waits for messages before returning an empty response. The default is 0 (short polling), which returns immediately and costs more because the consumer must poll repeatedly. Set to 20 for most workloads — it reduces API calls and cost with no downside for typical batch consumers.
Visibility timeout (visibilityTimeoutSeconds) is how long a message is hidden from other consumers after one consumer picks it up. The consumer must delete the message before this timeout expires; otherwise the message becomes visible again and may be processed a second time. The default is 30 seconds. Set this higher than your expected processing time — if tasks take 2 minutes, use at least 150 seconds.
Triggering a Lambda function
An SQS queue is one of the most common event sources for Lambda functions. When messages arrive, AWS invokes the function with a batch of messages. Your handler should process messages idempotently, because failed batches can be retried. Configure this using an SQS trigger on the Lambda function — not on the queue itself.
Key settings on the trigger:
batchSize— max messages per invocation (default: 10, max: 10,000).maxBatchWindowSeconds— max wait time before invoking with a partial batch (max: 300 seconds).
The Lambda handler receives messages in the Records array:
Connecting to other resources
Use connectTo on any compute resource (Lambda function, web service, worker service, etc.) to grant it access to the queue. Stacktape grants SQS send, receive, and delete permissions and injects ARN, NAME, and URL environment variables automatically.
For a queue named taskQueue, the injected environment variables are:
| Environment variable | Description |
|---|---|
STP_TASK_QUEUE_ARN | The queue's Amazon Resource Name |
STP_TASK_QUEUE_NAME | The queue name |
STP_TASK_QUEUE_URL | The queue URL (use this with the AWS SDK to send/receive messages) |
For more details on connectTo, see Connecting resources.
Sending a message from the connected Lambda function:
Queue policies
For Stacktape-managed compute resources (Lambda functions, web services, worker services, etc.), use connectTo to grant access — it handles IAM permissions and environment variables automatically. For cross-account access or granting specific AWS service principals (such as SNS) permission to send messages to the queue, use policyStatements. These custom access-control statements are merged with the policies Stacktape auto-generates. See the API Reference for the full policy statement shape.
EventBridge integration
An SQS queue can receive EventBridge events using the queue's events property. This routes matching events directly into the queue without writing any producer code. Choose exactly one EventBridge source: eventBusName for a Stacktape-managed bus, eventBusArn for an existing external bus, or useDefaultBus for the default AWS event bus.
The same EventBridge integration also supports delivery-failure routing and payload shaping through onDeliveryFailure, input, inputPath, and inputTransformer; use the API Reference for those less common options.
FIFO queues with EventBridge
When routing EventBridge events into a FIFO queue, you must set messageGroupId on the integration — SQS requires a message group ID for every message delivered to a FIFO queue. Messages in the same group are processed in strict order; different groups can be processed in parallel.
Alarms
Stacktape supports two alarm triggers for SQS queues:
sqs-queue-not-empty— fires when the queue has activity (any of: visible messages, in-flight messages, messages received, or messages sent are non-zero). Use this to detect a consumer that has stopped processing.sqs-queue-received-messages-count— fires when the number of received messages crosses athresholdCount. Use this to detect unexpected traffic spikes. Defaults to comparing the average messages received per period against the threshold; customize withstatisticandcomparisonOperator.
Define alarms in the queue config and deploy to apply changes. Export legacy Console rules into config; disabledGlobalAlarms excludes named legacy rules during migration. For more on alarms, see Alarms and Alert channels.
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
API Reference
SqsQueuePropsSQS Queue FAQ
When should I use an SQS queue vs an SNS topic?
Use an SQS queue when you have one consumer processing messages at its own pace — the queue holds messages until the consumer is ready. Use an SNS topic when you need fan-out: multiple subscribers each receive a copy of every message. A common pattern combines both: SNS fans out to multiple SQS queues, giving each consumer its own buffer.
How does Amazon SQS pricing work?
SQS uses pay-per-request pricing with no minimum fee. The first 1 million requests per month are included in the AWS Free Tier. After that, standard queues are cheaper per request than FIFO queues. Each 64 KB chunk of a message counts as one request. Long polling reduces costs by making fewer API calls.
What is the maximum message size for SQS?
The maximum message size is 256 KB (262,144 bytes). For larger payloads, the standard pattern is to store the data in an S3 bucket and send a reference (the S3 key) as the message body. You can configure a smaller max using maxMessageSizeBytes (minimum 1 KB).
Why does one bad message block my whole queue, and how do I stop it?
Without a dead-letter queue, a "poison" message that always fails processing keeps becoming visible and being retried forever, stalling the consumer. Configure a dead-letter queue with redrivePolicy: after maxReceiveCount failed attempts the message moves aside to the DLQ automatically, so the rest of the queue keeps flowing. Monitor the DLQ with an sqs-queue-not-empty alarm so you're notified when messages land there.
Can I use SQS with a container service instead of Lambda?
Yes. Use connectTo on a web service, worker service, or multi-container workload to get SQS permissions and the queue URL injected as environment variables. Your container application polls the queue using the AWS SDK. Unlike Lambda-based consumers, you manage the polling loop yourself.
My consumer keeps processing the same message twice — why?
A message is hidden from other consumers only for visibilityTimeoutSeconds (default 30s) after one consumer picks it up. If your handler takes longer than that to delete the message, the message becomes visible again and gets processed a second time. Set visibilityTimeoutSeconds comfortably above your expected processing time. Standard queues are also at-least-once by design, so handlers should always be idempotent; switch to a FIFO queue if you need exactly-once delivery.
Can I delay when messages become available to consumers?
Yes. Set delayMessagesSecond to a value between 0 and 900 (15 minutes); new messages stay invisible until the delay expires. This is useful when related data needs to settle before processing — for example, waiting a few seconds after an order is placed before sending a confirmation.