Troubleshoot messages not returned for an Amazon SQS ReceiveMessage API call
The following topics cover the most common causes why an Amazon SQS message may not be returned
to consumers, and how to troubleshoot them. For more information, see Why can't I receive messages from
my Amazon SQS queue?
Empty queue
To determine if a queue is empty, use long polling to call the ReceiveMessage API. You can also use the
ApproximateNumberOfMessagesVisible,
ApproximateNumberOfMessagesNotVisible, and
ApproximateNumberOfMessagesDelayed CloudWatch metrics. If all the metric values are
set to 0 for several minutes, the queue is considered empty.
In flight limit reached
If you use long polling and if the queue’s in flight limit (20000 for FIFO, 120000 for standard by default) is breached, Amazon SQS won't return error messages that exceed quota limits.
Message delay
If the Amazon SQS queue is configured as a delay queue,
or the messages were sent with message timers, then
the messages aren't visible until the delay time ends. To verify if a queue is configured as a
delay queue, use the GetQueueAttributes API DelaySeconds attribute, or from
the queue console under Delivery delay. Check the ApproximateNumberOfMessagesDelayed CloudWatch metric to understand if any
messages are delayed.
Message is in flight
If a different consumer has polled the message, the message will be in flight or invisible for the visibility timeout period. The additional polls might return an empty receive. Check the ApproximateNumberOfMessagesVisible CloudWatch metric to understand the number of messages that are available to be received. In the case of FIFO queues, if a message with the message group ID is in flight, then no more messages will be returned unless you delete the message, or it becomes visible. This is because message ordering is maintained at the message group level in a FIFO queue.
Polling method
If you are using short polling, (WaitTimeSeconds is 0) Amazon SQS samples a subset of its servers, and returns messages from only those servers. Therefore, you might not get the messages even if they are available for to be received. Subsequent poll requests will return the messages.
If you are using long polling, Amazon SQS polls all the servers and sends a response after collecting at least one available message, and up to the maximum number that's specified. If the value for ReceiveMessage WaitTimeSeconds is too low, you might not receive all the available messages.
