How to troubleshoot 500, 502 and 503 errors caused by Lambda@Edge functions in CloudFront?

Short description

Lambda@Edge 500, 502 and 503 errors indicate the following:

• HTTP 500 status code indicates that the Lambda function returned a run error.

• HTTP 502 status code indicates that the Lambda function response was incorrectly formed or included content that is not valid.

• HTTP 503 status code indicates that CloudFront is throttled due to Lambda service quotas (formerly known as limits).

See the following sections for the causes of the errors, and how to troubleshoot them.

Resolution

Lambda@Edge function returns a 500 error

A 500 run error results when CloudFront doesn’t get a response from Lambda. This happens because there are unhandled exceptions in the function, there’s an error in the code, or it's an unsupported run environment.

To resolve 500 error generated by Lambda@Edge, you must debug your code by adding logging statements for Lambda functions. To learn more, see Four Steps for Debugging your Content Delivery on AWS and review the information under I – Execution Errors. These logging statements write messages to CloudWatch log files that monitor the running of the CloudFront function. You can review those statements in the CloudWatch log files to verify that the function is working correctly.

For more information, see Lambda function errors in Node.js and Lambda function errors in Python.

Lambda@Edge function returns a 502 error

After the function runs, CloudFront receives a response from Lambda. A 502 error is returned if the object structure of the response doesn't conform to the Lambda@Edge event structure. A 502 error is also returned if the response contains not valid headers or other not valid fields.

To resolve 502 error generated by Lambda@Edge, check the Lambda@Edge function for the following common issues:

• Returned JSON object
• Missing required fields
• The response has an object that is not valid
• Adding or updating is disallowed or there are read-only headers
• Exceeding the maximum body size
• Characters or values are not valid

For more information, see Testing and debugging Lambda@Edge functions and Restrictions on edge functions.

Lambda@Edge function returns a 503 error

The Lambda service throttles executions in each Region, and returns a 503 error if you exceed the quota.

To resolve 503 error, check the Lambda@Edge CloudWatch metrics and log files for the following common issues:

• Concurrent executions on per Region basis
• Functions quotas reached

For more information, see Quotas on Lambda@Edge.

Note: You must review CloudWatch log files in the correct Region to see the log files created when CloudFront executed the Lambda function.

---

Related information

Lambda@Edge design best practices