---
cuppy_hub: aws
cuppy_path: reference/sqs/errors.md
cuppy_section: docs
cuppy_doc: Y6S2-0KZ4
cuppy_doc_uuid: 937381bc-3390-451c-ab8c-26fb8fc3c1de
cuppy_permalink: https://cuppy.io/aws/d/Y6S2-0KZ4
cuppy_version: 4
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/aws/docs/reference/sqs/errors
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: eed2982e430595e52b996a6eca9aa0e390b7daf02dcb8d4e8c69a734cca39fa0
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Amazon SQS errors

**SQS errors are mostly about the wrong queue URL, a stale receipt handle, a bad message, or KMS.** The worst SQS failures raise no error at all, so the silent-failure table comes first. Names below are the SDK v3 exception names; descriptions follow the SDK's own documentation.

## Silent failures

| Symptom | Cause → fix | Check |
|---|---|---|
| `ReceiveMessage` returns nothing, but the queue has messages | **Short polling** samples only some servers. Use `WaitTimeSeconds: 20` or set `ReceiveMessageWaitTimeSeconds` on the queue | `aws sqs get-queue-attributes --queue-url <u> --attribute-names ReceiveMessageWaitTimeSeconds ApproximateNumberOfMessages` |
| Same message processed twice | At-least-once delivery on standard queues, or visibility expired before you deleted. Make consumers idempotent, extend visibility for long work, and delete after success (`guides/sqs/send-and-receive.md`) | Compare processing time with the queue's `VisibilityTimeout`; a message's `ApproximateReceiveCount` > 1 shows redelivery |
| Messages vanish from the DLQ soon after arriving | Standard queues keep the original enqueue time. Give the DLQ **longer retention** than the source | `MessageRetentionPeriod` on both queues (`get-queue-attributes`) |
| A FIFO group "stops" | A received message in that group wasn't deleted, so the group is blocked until its visibility expires or it reaches the DLQ | `ApproximateNumberOfMessagesNotVisible` > 0 while the group stalls; the consumer's logs for the undeleted message |
| Messages from **SNS, EventBridge or S3** never arrive in an encrypted queue | The queue uses the AWS managed key `aws/sqs`, whose policy can't be changed, or the customer managed key's policy lacks the service principal (`kms:GenerateDataKey`, `kms:Decrypt`) (`reference/sqs/queue-settings-and-encryption.md`) | `get-queue-attributes --attribute-names KmsMasterKeyId SqsManagedSseEnabled`; then `aws kms get-key-policy --key-id <k> --policy-name default` |
| …and the queue isn't encrypted | The **queue policy** doesn't allow `sqs:SendMessage` for that service principal with `aws:SourceArn` = the topic, rule or bucket (`patterns/sns-to-sqs-fanout.md`) | `get-queue-attributes --attribute-names Policy`: look for the service principal and `aws:SourceArn` |
| Lambda trigger fills the DLQ with unprocessed messages | Throttling plus a low `maxReceiveCount` (`patterns/sqs-to-lambda.md`) | The function's `Throttles` metric and the queue's `RedrivePolicy` |

## Exceptions

| Exception | Meaning → fix | Check |
|---|---|---|
| `QueueDoesNotExist` | "Ensure that the QueueUrl is correct and that the queue has not been deleted." Check the account and Region in the URL. A queue deleted less than 60 s ago can't be re-created yet | `aws sqs get-queue-url --queue-name <n> --region <r>` with the same credentials |
| `QueueDeletedRecently` | You must wait **60 seconds** after deleting a queue before creating one with the same name | Wait 60 s and retry |
| `QueueNameExists` | The name exists **with different attributes**. A create with identical attributes returns the existing queue | `get-queue-attributes --attribute-names All` on the existing queue and diff with your request |
| `OverLimit` | An action would break a limit. For example, `ReceiveMessage` when the maximum number of **in-flight** messages is reached: delete or let messages time out faster, or add queues | `ApproximateNumberOfMessagesNotVisible` (in flight) in CloudWatch or `get-queue-attributes` |
| `RequestThrottled` | The request rate is too high for the queue or the recipient. Back off; batch sends and deletes | CloudTrail or SDK retry logs for the call rate; batch sizes in your code |
| `ReceiptHandleIsInvalid` | The receipt handle isn't valid: use the handle from the receive of the message you're deleting. (`InvalidIdFormat` is deprecated into this) | Log the receipt handle at receive and at delete: they must be the same receive |
| `MessageNotInflight` | `ChangeMessageVisibility` on a message that isn't in flight, for example because visibility already expired (the hub's reading) | Was the visibility already expired? Compare elapsed time with `VisibilityTimeout` |
| `InvalidMessageContents` | The body has characters outside the allowed Unicode set (`#x9`, `#xA`, `#xD`, `#x20`–`#xD7FF`, `#xE000`–`#xFFFD`, `#x10000`–`#x10FFFF`). Encode binary as base64 | Scan the body for control characters other than tab, LF and CR |
| `BatchRequestTooLong` | All messages together exceed the size limit. Messages max out at 1 MiB; split the batch | Sum the encoded bodies + attributes of the batch |
| `TooManyEntriesInBatchRequest` | More than **10** entries | Count the entries |
| `BatchEntryIdsNotDistinct` / `InvalidBatchEntryId` / `EmptyBatchRequest` | Duplicate entry IDs / IDs outside ≤80 alphanumeric, `-`, `_` / no entries | Print the entry IDs |
| `InvalidAttributeName` / `InvalidAttributeValue` | Unknown queue attribute / bad value, for example a `RedrivePolicy` that isn't valid JSON, or a retention outside 60 s – 14 days | `aws sqs get-queue-attributes --attribute-names All` to see valid names; validate JSON values with a parser |
| `PurgeQueueInProgress` | The queue was purged within the last **60 seconds**. Wait | CloudTrail `PurgeQueue` in the last minute |
| `InvalidSecurity` | The request wasn't made over HTTPS or wasn't signed with SigV4. Usually a custom HTTP client, never the SDK | The client's endpoint scheme (`https://`) and signing |
| `KmsAccessDenied` | The caller lacks KMS access to the queue's key. Producers need `kms:GenerateDataKey` + `kms:Decrypt`; consumers need `kms:Decrypt` (DLQ consumers on the source queue's key too) (`reference/kms/key-policies-and-errors.md`) | `aws kms get-key-policy` for the queue's key, and the caller's IAM policy (`reference/kms/key-policies-and-errors.md`) |
| `KmsDisabled`, `KmsInvalidState`, `KmsNotFound`, `KmsInvalidKeyUsage`, `KmsOptInRequired`, `KmsThrottled` | The queue's KMS key is disabled, pending deletion, missing, of the wrong usage, or throttled. Fix the key or switch to SSE-SQS. Throttling grows with the number of distinct principals; raise `KmsDataKeyReusePeriodSeconds` (up to 86,400) | `aws kms describe-key --key-id <k> --query KeyMetadata.KeyState` |
| `UnsupportedOperation` | The operation isn't supported, for example a FIFO-only parameter on a standard queue (the hub's example) | Is the queue FIFO (`.fifo` suffix, `FifoQueue` attribute) and the parameter FIFO-only, or the reverse? |
| `InvalidAddress`, `ResourceNotFoundException` | An invalid ID or ARN / a referenced resource doesn't exist | Compare the ID or ARN with `get-queue-url` / `get-queue-attributes --attribute-names QueueArn` |

Errors that reach a **Lambda** consumer as its own exceptions are in `reference/lambda/errors.md`. IAM denials (`AccessDenied`) are covered by `guides/iam/fix-access-denied.md`.

## When none of these fits

Read the queue's attributes (`aws sqs get-queue-attributes --queue-url <url> --attribute-names All`): policy, KMS key, redrive policy, visibility timeout. Then compare `ApproximateNumberOfMessagesVisible` and `ApproximateAgeOfOldestMessage` with the consumer's activity. Look up the failing call's `errorCode` in CloudTrail (`guides/cloudtrail/find-who-did-what.md`). Keep the request ID.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->