How do I troubleshoot Lambda function failures?

Last updated: 2019-10-16

When I run my AWS Lambda function, it fails with an error. How do I troubleshoot the failure?

Short Description

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:

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:


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


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:

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.


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.