# SQS queues and consumers (/connectors/aws/how-to/sqs-queues-and-consumers)



This guide covers the SQS surface end to end: queue lifecycle, send/receive/delete, visibility
timeouts, the in-flight cap, receipt handles, long polling, batch operations, message attributes,
FIFO queues, and DLQ/redrive. Every SQS queue is a native KubeMQ **Queue** channel `sqs.{name}`
(see [Channel mapping](/connectors/aws/reference/channel-mapping)). The SQS surface ships
**18 actions** (see [Capabilities](/connectors/aws/reference/capabilities)).

## Queue lifecycle [#queue-lifecycle]

* `CreateQueue` — idempotent on an existing name with the same attributes; a **FIFO** queue uses
  the `.fifo` name suffix. Re-creating the same name with **different** attributes returns
  `QueueNameExists`.
* `GetQueueUrl` — returns the path-style URL `{scheme}://{host}/{AccountId}/{name}`.
* `ListQueues` — pagination plus `QueueNamePrefix`; results are **not** authorization-filtered.
* `DeleteQueue` — removes the registry record, best-effort broker purge, drops node-local
  in-flight.
* `PurgeQueue` — an `AckAllQueueMessages`; a **60 s cooldown** applies (a second purge within the
  window returns `PurgeQueueInProgress`).
* `GetQueueAttributes` / `SetQueueAttributes` — see below.
* `TagQueue` / `UntagQueue` / `ListQueueTags` — ≤ 50 tags.
* `ListDeadLetterSourceQueues` — reverse-resolves queues whose `RedrivePolicy` names this queue.

<Callout type="info">
  **The registry is authoritative.** Only queues created via the AWS API are visible; operating on a
  native `sqs.foo` channel that was never `CreateQueue`d returns `NonExistentQueue`.
</Callout>

## Queue attributes [#queue-attributes]

**Writable** (`SetQueueAttributes` is a partial-update overlay; it is **not** retroactive to
messages already in the queue):

| Attribute                          | Range                                                                  |
| ---------------------------------- | ---------------------------------------------------------------------- |
| `DelaySeconds`                     | 0–900                                                                  |
| `MaximumMessageSize`               | 1024–262144                                                            |
| `MessageRetentionPeriod`           | 60–1209600                                                             |
| `VisibilityTimeout`                | 0–43200                                                                |
| `ReceiveMessageWaitTimeSeconds`    | 0–20                                                                   |
| `RedrivePolicy`                    | raw JSON `{deadLetterTargetArn, maxReceiveCount}` (registry-validated) |
| `FifoQueue` (create-only)          | must match the `.fifo` suffix                                          |
| `ContentBasedDeduplication` (FIFO) | bool                                                                   |
| `DeduplicationScope` (FIFO)        | `queue` \| `messageGroup`                                              |

An unknown attribute name, or a KMS/SSE attribute (`KmsMasterKeyId`, `Policy`, …), on a `Set`
returns `InvalidAttributeName`.

**Read-only on `Get`:** `QueueArn`, `ApproximateNumberOfMessages` (broker stats, 2 s TTL),
`ApproximateNumberOfMessagesNotVisible` (node-local in-flight), `ApproximateNumberOfMessagesDelayed`
(&#x2A;*always `"0"`**), `CreatedTimestamp`, `LastModifiedTimestamp`; FIFO adds `FifoQueue` /
`ContentBasedDeduplication` / `DeduplicationScope`.

<Callout type="info">
  **`ApproximateNumberOfMessagesDelayed` is always `"0"`.** The connector does not track
  delayed-message counts. See [Capabilities](/connectors/aws/reference/capabilities).
</Callout>

## Send / receive / delete [#send--receive--delete]

The round-trip is three actions:

1. `SendMessage` — returns `MessageId`, `MD5OfBody`, and (if attributes are present)
   `MD5OfMessageAttributes`.
2. `ReceiveMessage` — returns the message body plus a **receipt handle**.
3. `DeleteMessage(receiptHandle)` — acks the message off the queue (`AckRange`). It is
   **idempotent**: an unknown receipt handle returns success.

### Visibility timeout [#visibility-timeout]

A received message is hidden for a visibility window before it becomes receivable again.
Precedence: per-request `VisibilityTimeout&#x60; (0–43200) &#x2A;*>*&#x2A; the queue default &#x2A;*>** 30 s.
`ChangeMessageVisibility(timeout>0)` moves the deadline; `ChangeMessageVisibility(0)` NAcks the
message so it becomes visible again at the **tail**. A 250 ms sweeper NAcks expired in-flight
entries back to the tail, and `ApproximateReceiveCount` increments on re-receive.

### Receipt handles are node-local [#receipt-handles-are-node-local]

A receipt handle is an opaque `base64url(json)` token carrying
`{version, node, txnId, queue, seq, receivedMs, salt}`. Decoding validates `version==1` **and** the
**node** match.

<Callout type="warn">
  **Receipt handles are node-local → a sticky LB is required in clusters.** A receipt handle minted
  on one node is rejected on another (`ReceiptHandleIsInvalid`). In-flight tracking and SNS delivery
  state are node-local too, so cluster deployments need a **sticky load balancer** (session
  affinity). Single-node deployments are unaffected. See
  [Connectivity and security](/connectors/aws/how-to/connectivity-and-security) and
  [Migration from AWS](/connectors/aws/reference/migration-from-aws).
</Callout>

### In-flight cap [#in-flight-cap]

Received-but-not-deleted messages count against a per-queue / per-node cap, `MaxInflightPerQueue`
(default 20,000). Exceeding it returns `OverLimit`.

## Long polling [#long-polling]

* `WaitTimeSeconds` is 0–20; `MaxNumberOfMessages` is 1–10.
* A parked long-poll slot pool (`MaxConcurrentPolls`, default 1024); when it is exhausted a request
  **degrades to a short poll** (it does not error).
* Wire waits are chunked into ≤ 2 s sub-Gets for shutdown responsiveness.

<Callout type="info">
  **An empty-queue short poll has a \~1 s latency floor.** Because the broker wait granularity is
  integer seconds (1 s minimum), a `ReceiveMessage` on an **empty** queue returns within \~1 s, not
  instantly. Queues with available messages respond at once.
</Callout>

## Batch operations [#batch-operations]

`SendMessageBatch` / `DeleteMessageBatch` / `ChangeMessageVisibilityBatch` take ≤ 10 entries.
`SendMessageBatch` returns per-entry `Successful[]` / `Failed[]`:

* a single oversize entry → that entry is `Failed` with `InvalidParameterValue` (SenderFault), the
  rest `Successful`;
* an **aggregate** body+attributes over 262,144 bytes → the **whole batch** is rejected with
  `BatchRequestTooLong`.

## Message attributes [#message-attributes]

* Up to 10 message attributes; the name is ≤ 256 chars with no `AWS.` / `Amazon.` prefix; the
  `DataType` is `String` / `Number` / `Binary` (plus custom subtypes like `String.x`). They
  round-trip losslessly through the tag codec `sqs_attr_{Name} = {DataType}|{value}` (Binary is
  base64).
* **Message system attributes:** only `AWSTraceHeader` (DataType `String`) is accepted; anything
  else returns `InvalidParameterValue`. It is stored as `sqs_trace_header`.

See [Channel mapping](/connectors/aws/reference/channel-mapping) for the full mapping and the
MD5 algorithms.

## FIFO queues [#fifo-queues]

A `.fifo` suffix makes a queue FIFO (`FifoQueue` is immutable post-create):

* **`MessageGroupId` is required** on a FIFO send (1–128 printable ASCII characters) — omitting it
  returns `InvalidParameterValue`;
* per-message **`DelaySeconds` is rejected** → `InvalidParameterValue`;
* `ReceiveRequestAttemptId` is accepted and ignored;
* each group maps to its own channel `sqs.{name}.fifo.g.{enc(group)}`;
* **deduplication** uses an explicit `MessageDeduplicationId`, or the SHA-256 of the body when
  `ContentBasedDeduplication` is on; a duplicate within the **5-minute** LRU window returns the
  **original** `MessageId` / `SequenceNumber` **without re-publishing**;
* **per-group ordering** allows at most one un-acked downstream `Get` per group; `ReceiveMessage`
  drains groups round-robin, ≤ 10 total.

<Callout type="info">
  **`SequenceNumber` differs between send and receive.** The 20-digit zero-padded `SequenceNumber`
  is the broker &#x2A;*send-timestamp (UnixNano)** on send and the **true broker sequence** on receive. It
  is still strictly increasing per group for serialized sends. See
  [Channel mapping](/connectors/aws/reference/channel-mapping).
</Callout>

Full FIFO reliability detail is in [Reliability](/connectors/aws/how-to/reliability).

## DLQ / redrive [#dlq--redrive]

Set a queue `RedrivePolicy` of `{deadLetterTargetArn, maxReceiveCount}`. The connector stamps each
message with `MaxReceiveCount` / `MaxReceiveQueue=sqs.{dlq}` at send; the message broker moves the
message to the DLQ when the receive count **exceeds** `maxReceiveCount`, surfacing
`DeadLetterQueueSourceArn` on the redriven message. `ListDeadLetterSourceQueues` reverse-resolves.
See [Reliability](/connectors/aws/how-to/reliability).

## At-least-once and graceful shutdown [#at-least-once-and-graceful-shutdown]

Unacked deliveries are NAcked back to the queue tail by the 250 ms sweeper or on graceful shutdown
(≤ 10 s); the registry survives restart (a shared `StorePath`). **Exactly-once is not provided** —
design consumers to be idempotent.

## Error quick reference [#error-quick-reference]

| Trigger                                                                      | AWS error code           |
| ---------------------------------------------------------------------------- | ------------------------ |
| Operate on a queue not in the registry                                       | `NonExistentQueue`       |
| `CreateQueue` same name + different attributes                               | `QueueNameExists`        |
| `PurgeQueue` within the 60 s cooldown                                        | `PurgeQueueInProgress`   |
| Unknown / KMS attribute on `SetQueueAttributes`                              | `InvalidAttributeName`   |
| Oversize batch entry / bad attribute / non-`AWSTraceHeader` system attribute | `InvalidParameterValue`  |
| `SendMessageBatch` aggregate over 262,144 B                                  | `BatchRequestTooLong`    |
| Receipt handle from another node / malformed                                 | `ReceiptHandleIsInvalid` |
| In-flight over `MaxInflightPerQueue`                                         | `OverLimit`              |
| FIFO send without `MessageGroupId` / with per-message `DelaySeconds`         | `InvalidParameterValue`  |

## Related [#related]

<Cards>
  <Card title="SNS fan-out" href="/connectors/aws/how-to/sns-fan-out" description="Topics, subscriptions, the confirmation flow, MessageAttributes filtering, raw vs enveloped, and FIFO topics." />

  <Card title="Reliability" href="/connectors/aws/how-to/reliability" description="FIFO dedup, DLQ/redrive, the SNS retry pipeline, and at-least-once delivery." />

  <Card title="Error codes" href="/connectors/aws/reference/error-codes" description="The full AWS error-code table the connector returns." />
</Cards>