Amazon SQS errors
Look up an SQS exception by name — QueueDoesNotExist, OverLimit (too many in-flight), RequestThrottled, ReceiptHandleIsInvalid, MessageNotInflight, InvalidMessageContents, batch errors, QueueDeletedRecently (60 seconds), QueueNameExists, PurgeQueueInProgress, InvalidSecurity, the Kms* family — plus the silent failures (empty receives, duplicates, messages expiring in the DLQ, messages never arriving from SNS, EventBridge or S3) with cause and fix.
markdownreferencev4Y6S2-0KZ4stage: operatetrust: officialservice: sqsinterface: anyQueueDoesNotExistOverLimitin-flight messages limitRequestThrottledReceiptHandleIsInvalidMessageNotInflightInvalidMessageContentsBatchRequestTooLongTooManyEntriesInBatchRequestBatchEntryIdsNotDistinctEmptyBatchRequestInvalidBatchEntryIdInvalidAttributeNameInvalidAttributeValueQueueDeletedRecentlyQueueNameExistsPurgeQueueInProgressInvalidSecurityKmsAccessDeniedKmsDisabledKmsNotFoundKmsThrottledUnsupportedOperationSQS empty receiveSQS duplicate messagesDLQ messages expiredSNS to SQS not delivered
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.