How do I troubleshoot Lambda function failures?

Lambda function failures are commonly caused by:

• Permissions issues
• Code issues
• Network issues
• Throttling
• Invoke API 500 and 502 errors

Depending on your Lambda code and configuration, you can use these AWS services and features to determine the cause:

• AWS CloudTrail
• Amazon CloudWatch Logs
• AWS X-Ray
• Lambda metrics in CloudWatch

Review the following common issue types to determine which service or feature to use and where to find more information and troubleshooting instructions.

Permissions issues

CloudTrail captures API calls in your AWS account as events. When your Lambda function fails to invoke, review the CloudTrail log entries for Lambda.

The requester making calls to Lambda must have the AWS Identity and Access Management (IAM) permissions required to invoke your function. If the requester doesn't have access, update your Lambda function permissions to grant them access. For more information, see Troubleshooting AWS Lambda Identity and Access.

Code issues

CloudWatch Logs

For details of your Lambda function's failure, view Lambda logs in CloudWatch. For more information, see the logging instructions for the programming language that you're using:

• AWS Lambda Function Logging in Python
• AWS Lambda Function Logging in Node.js
• AWS Lambda Function Logging in Java
• AWS Lambda Function Logging in Go
• AWS Lambda Function Logging in C#
• AWS Lambda Function Logging in PowerShell
• AWS Lambda Function Logging in Ruby

X-Ray

If your Lambda function uses downstream AWS resources, microservices, databases, or HTTP web APIs, use X-Ray to help troubleshoot issues.

Dependencies

If your Lambda function's deployment package includes any dependencies, make sure that your code can import them successfully. For more information, see these instructions for the programming language that you're using:

• AWS Lambda Deployment Package in Python
• AWS Lambda Deployment Package in Node.js
• AWS Lambda Deployment Package in Java
• AWS Lambda Deployment Package in Go
• AWS Lambda Deployment Package in C#
• AWS Lambda Deployment Package in PowerShell
• AWS Lambda Deployment Package in Ruby

Or, you can use Lambda layers to add dependencies outside of your deployment package.

Network issues

If your Lambda function is connected to an Amazon Virtual Private Cloud (Amazon VPC), make sure that everything is correctly configured. For more information, see Configuring a Lambda Function to Access Resources in a VPC.

If your Amazon VPC-enabled Lambda function needs to make calls to the internet, make sure to give it internet access.

Throttling

If requests to invoke your Lambda function arrive faster than it can scale or exceed your concurrency limit, the requests fail with a 429 throttling error. For more information, see AWS Lambda Function Scaling.

To help troubleshoot the cause, monitor the Lambda metrics ConcurrentExecutions, UnreservedConcurrentExecutions, and Throttles using CloudWatch. For more information, see AWS Lambda CloudWatch Metrics.

Invocation API 502 and 500 errors

If your Lambda function fails with a 502 or 500 server error, review these troubleshooting instructions.

For a list of possible errors with descriptions, see Errors in the Lambda Invoke API reference.