Troubleshooting Queues
Symptoms you can hit with queues and SQS clients, their causes, and the fix.
InvalidClientTokenId from an SQS client
Cause: The access key does not exist, is inactive or expired, belongs to a removed user, or cannot sign requests: keys whose kind in Access keys reads "API and CLI" are not accepted by the SQS endpoint. A session token sent with a key that is not temporary is refused the same way.
Fix: Create a new key under Identity, Access keys; its kind reads "API, CLI and S3".
SignatureDoesNotMatch
Cause: The secret is wrong, or the client signs for another address than the one it calls.
Fix: Check the secret, and set the client's endpoint to the origin of the queue URL,
https://sqs.<your platform domain>.
InvalidAction: "Only the SQS JSON protocol is supported"
Cause: The SDK or CLI is old enough to speak SQS's XML query protocol.
Fix: Upgrade it to a release from November 2023 or later.
QueueDoesNotExist for a queue you can see in the console
Cause: The queue URL carries another organization's id, or the name is misspelled.
Fix: Get the URL with GetQueueUrl, or copy Queue URL from the queue's page.
AccessDenied, or 403 "Forbidden"
Cause: The key's user lacks the queue: action on that queue. Receiving needs
queue:ReceiveMessage, which QueueReadOnlyAccess does not include.
Fix: Attach a policy that allows the action; see Security.
A redrive moved fewer messages than the dead-letter queue holds
Cause: The rest are in flight in the dead-letter queue, past their retention and not yet removed, or beyond the 100,000 messages one redrive moves; or, without a destination, the queue they came from has been deleted, or they were sent to the dead-letter queue directly.
Fix: Wait for their visibility timeout and redrive again, or redrive with a destination; see Redrive a dead-letter queue.
A FIFO receive returns nothing though messages are waiting
Cause: Every group with waiting messages has a message in flight.
Fix: Delete or release everything you received from those groups, or wait for the visibility timeout. See FIFO queues.
A FIFO send returns an old message id and nothing new arrives
Cause: Its deduplication id, or with content-based deduplication its body, was sent in the last five minutes.
Fix: Use a new deduplication id.
The same message is processed twice
Cause: The consumer took longer than the visibility timeout, so the message was delivered again, or its delete used the receipt handle of an older receive.
Fix: Raise the queue's visibility timeout, or extend it for a long job (see Change the visibility of a message), and make processing idempotent.
429 with code Throttling, or RequestThrottled
Cause: Your organization makes more than 100 queue requests a second.
Fix: Wait before retrying (the API's 429 carries a Retry-After header; the SQS endpoint's
RequestThrottled does not), and batch: one request can send, receive or delete 10 messages.
Long polling cuts empty receives.