Why doesn't my Amazon SQS queue invoke my Lambda function?

Resolution

Confirm your configuration requirements

Take the following actions:

• Confirm that you created an Amazon SQS event source mapping that polls the queue and invokes your Lambda function.
• Confirm that the Lambda function AWS Identity and Access Management (IAM) role has the required permissions to get messages from the SQS queue. The Lambda function IAM role must have DeleteMessage, GetQueueAttributes, and ReceiveMessage API permissions.
• View Amazon CloudWatch metrics for your function for invocations to confirm that Lambda invoked your function.
• If SQS messages aren't visible or sent to the SQS queue, then make sure that the producer has the required permissions. If you use an encrypted SQS queue, then the producer must have SendMessage, GenerateDataKey, and Decrypt API permissions.

Confirm that messages exist in the SQS queue

Check CloudWatch metrics for the ApproximateNumberOfMessages metric. If the metric is 0, then messages didn't reach the queue. Confirm that the producer runs, sends the messages to the correct queue URL, and has the preceding required permissions.

Review event source mapping metrics for PolledEventCount, InvokedEventCount, FilteredOutEventCount, FailedInvokeEventCount, and DeletedEventCount metrics to find out where the messages went.

For example, if PolledEventCount is non-zero but InvokedEventCount is 0 and FilteredOutEventCount matches PolledEventCount, then your filter criteria drop every message.

If PolledEventCount is 0 but the queue has messages, then the event source mapping isn't polling. Check the processing state for events that are polled, invoked, filtered out, deleted, dropped, failed, or sent to on-failure destination.

For more information, see Introducing new Event Source Mapping (ESM) metrics for AWS Lambda.

Check that the Lambda function and SQS queue URLs are correct

Confirm that the Lambda function Amazon Resource Name (ARN) and the SQS queue URL in the event source mapping are correct.

1. Open the Lambda console.
2. In the navigation pane, choose Functions.
3. Select the function that you want to check.
4. Choose the SQS trigger and expand it to check that the SQS queue URL is correct.
5. Confirm that the trigger status is Enabled.
6. (Optional) If the trigger shows Disabled, then see Why did my Lambda Amazon SQS trigger get deactivated?

Check the Lambda function permissions

Make sure that the Lambda function execution role has the Amazon SQS API permissions ReceiveMessage, DeleteMessage, and GetQueueAttributes to poll the SQS queue. Also check the SQS queue access policy for any Deny statements that block requests from the Lambda execution role.

It's a best practice to attach the AWS managed policy AWSLambdaSQSQueueExecutionRole to your execution role for all required permissions. For more information, see Creating an SQS event source mapping.

Check the encryption settings for the queue

If the SQS queue uses AWS Key Management Service (AWS KMS) encryption, then the Lambda execution role requires Decrypt permission. Also, confirm that the AWS KMS key policy allows the Lambda role to decrypt.

Note: Amazon SQS queues encrypted with the default AWS managed key can't invoke a Lambda function in a different AWS account. Use a customer managed key for cross-account configurations.

Check if the Lambda function throttled

Lambda has a regional concurrency limit. If other functions in the same AWS Region use all available capacity, then your function throttled.

Take the following actions:

• If reserved concurrency is set to 0, then all invocations are throttled. Set reserved concurrency to at least 1 or remove the reservation.
• If maximum concurrency is configured on the event source mapping, then it limits how many concurrent instances the event source mapping can invoke. Make sure that your function's reserved concurrency is greater than or equal to the maximum concurrency for all Amazon SQS event sources on the function.
• Check the function's Throttles metric and the Region's ConcurrentExecutions metric in CloudWatch.

For more information, see How do I troubleshoot Lambda function "Rate exceeded" and "TooManyRequestsException" throttling errors?

Confirm that there are no other active consumers on the same SQS queue

If another consumer receives messages first, then your function doesn't receive messages when it polls the SQS queue. For example, a second Lambda function, an Amazon Elastic Compute Cloud (Amazon EC2) instance, or programmatic polling. Use the Amazon SQS console to confirm that there aren't any other active triggers.

Note: Programmatic consumers that use ReceiveMessage API calls don't appear in the Amazon SQS console.

Check for SQS event source filters

If your event source mapping has filter criteria, then Amazon SQS discards messages that don't match the filter criteria without invoking your function.

1. Open the Lambda console.
2. In the navigation pane, choose Functions.
3. Select the function that you want to check.
4. Choose the SQS trigger, and then confirm the Filter criteria.
5. If a filter is configured, then remove the filter temporarily.
6. If the function invokes after the filter is removed, then update the filter to match the message format.
   Note: To filter on message content, nest your pattern under the JSON message body key. For example, {"body": {"RequestCode": ["BBBB"]}}). If the message body is in plain string, then use string matching on the body key instead.

For more information, see Control which events Lambda sends to your function.

Prevent infinite loops

If your Lambda function fails on every invocation, then messages return to the queue after the visibility timeout. Then, messages reprocess in an infinite loop.

Complete the following steps:

1. Configure a dead-letter queue (DLQ) on the SQS queue with a maxReceiveCount redrive policy.
2. Set the visibility timeout to at least 6 times your Lambda function timeout.
   Note: Lambda recursive loop detection automatically stops loops between Lambda, SQS, and Amazon Simple Notification Service (Amazon SNS) after 16 invocations.

For more information, see Why did my Lambda function retry valid Amazon SQS messages and place them in my dead-letter queue?

Related information

Using Lambda with Amazon SQS

Why did my Lambda Amazon SQS trigger get deactivated?

Why isn't my Lambda function with an Amazon SQS event source scaling optimally?