How do I troubleshoot QueueDoesNotExist errors when making API calls to my Amazon SQS queue?
Last updated: 2021-08-24
When I make API calls to my Amazon Simple Queue Service (Amazon SQS) queue, I receive a QueueDoesNotExist error similar to the following:
"The specified queue does not exist for this wsdl version."
Why am I getting this error, and how can I troubleshoot the issue?
QueueDoesNotExist errors can result from various Amazon SQS API calls, including GetQueueAttributes, SendMessage, and DeleteMessage. To troubleshoot this error, review the following possible causes and resolution steps:
Incorrect queue URL
Verify that the queue URL provided in the request is correct and contains no typos.
Important: If the destination queue type is FIFO, you must append the suffix .fifo to the queue URL.
A QueueDoesNotExist exception returns when the request is made to the incorrect AWS Region. The software development kit (SDK) and AWS Command Line Interface (AWS CLI) don’t pick up the destination Region from the queue URL. Instead, the Region is determined by the client configuration.
You must correctly configure the Region on the Amazon SQS client before making an API call. Review the Amazon SQS client configuration to confirm that the correct Region is configured on the client. If a Region isn’t configured on the client, then the SDK or AWS CLI chooses the Region from the configuration file or the environment variable. If a Region isn’t found in the configuration file, then the SDK sets the Region to us-east-1 by default.
If the failed API call is supported by AWS CloudTrail, then verify all Regions in the customer account for the failed Amazon SQS operation. Verifying all Regions can help determine if the Region is the cause of the issue.
You can also verify the Region of the request by activating the debug log on the SDK or AWS CLI. Debug logs show the destination host for the request.
Example: Host: sqs.us-east-1.amazonaws.com
Queue recently purged or deleted
You might temporarily receive a QueueDoesNotExist error if the queue was recently purged. Identify the timestamp of the failed API call, and then verify CloudTrail for any PurgeQueue operations around the time of the error.
The error can also occur when the queue is deleted if the queue is part of an AWS CloudFormation or similar deployment stack. Updates to or deletion of a stack can cause the queue to be deleted and recreated. If the API call is made to the queue during deletion, the request can fail with a QueueDoesNotExist error. Verify CloudTrail for any DeleteQueue operations during the time of the error.
Cross account GetQueueUrl
For API calls, the SDK or AWS CLI usually take the destination queue account number from the queue URL. However, the GetQueueUrl API call doesn’t provide a queue's AWS account in the request. This means that by default the request is made against the caller account. If the request is intended for a cross account queue, then you must specify the destination queue account number as the API call QueueOwnerAWSAccountId parameter.
Message moved to a dead-letter queue
For standard SQS queues, when a dead-letter queue (DLQ) is configured, messages are moved to the DLQ after retries. QueueDoesNotExist errors can occur if you perform a DeleteMessage operation using an old ReceiptHandle from the main queue after the message is moved to the DLQ. You must delete messages within the configured VisibilityTimeout window.
If you contact AWS Support for additional troubleshooting, be sure to identify the RequestId and timestamp of the failed API calls.