Introductory Guide to Debugging Lambda Configuration Errors

It shouldn’t be a surprise that Lambda configuration error is one of the most common error messages, and we all know AWS error messages aren’t known for being especially detailed. Oftentimes you will come across other vague error messages like “encoding not enabled,” or “stream is failing,” and depending on the context, this could mean your services could be completely down.

The Lambda configuration error is as generic as it gets; there are dozens of configuration attributes you can set for your Lambda function, and if you don’t know them all by heart, anything or everything could be the culprit here.

What does “Lambda Configuration Error” mean?

This error can have many causes, but it simply means that the Lambda service can’t reach your handler function.

Lambda is a function as a service (FaaS) offering and tries to simplify hosting. While virtual machines and containers are long-running servers that hold state, FaaS removes state and only executes a function. The function receives input and generates output or has side-effects.

When you want to use Lambda, you have to supply it with a supported programming language function. If this function is missing or can’t be reached due to other problems, you will end up with the dreaded Lambda configuration error.

How do I fix it?

The error can have multiple causes, but they all break down to a path problem.

If you create a Lambda function with some kind of infrastructure as code (IaC) tool, you must supply it with a path to the function; otherwise, Lambda doesn’t know what it should execute in case of an event.

How does Lambda find function definitions?

Let’s look at an AWS SAM example.

AWSTemplateFormatVersion : '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
MyFunction:
Type: AWS::Serverless::Function
Properties:
Runtime: nodejs14.x
Handler: index.handler
CodeUri: ./lambda-code

Our MyFunction resource has three properties: Runtime, Handler, and CodeUri.

The Runtime tells AWS Lambda which programming language we are using. The other two, Handler and CodeUri, tell it where to find the actual function code.

Virtually all IaC tools that support Lambda functions use these two properties.

The CodeUri tells the service where the code files are located. In the case of AWS SAM, this is a path to the directory where the file with your function definition is located in. But this is just some convenience AWS SAM provides; after all, Lambda can’t load code from your local machine; it has to be in the cloud, in a ZIP archive uploaded to an S3 bucket. So, usually, CodeUri will point to this ZIP archive in the cloud and not your local content.

In the example above, the CodeUri points to ./lambda-code, so AWS SAM will bundle all files in there into a ZIP archive and upload it to an S3 bucket for you.

The next part is the Handler property, which starts where the CodeUri finished. The CodeUri pointed Lambda to a ZIP archive; now, Lambda needs to figure out where you implemented that function inside that file. Depending on your function’s size, you could have ended up with quite some files in that archive.

The most common path in the Handler property for the Lambda function that uses the Node.js runtime is probably index.handler. Everything before the dot is a file path, and the string after the dot is the name of the exported function in that file. Node.js developers use index.js files as their application entry files, so starting with index is common.

Let’s say our project is inside /home/user/dev/project. This means our AWS SAM template yaml file is at /home/user/dev/project/template.yml

The CodeUri in that template states the Lambda function code is at ./lambda-code, so AWS SAM will bundle the content of /home/user/dev/project/lambda-code into a ZIP file and upload it to an S3 bucket.

The Handler property in that template says the handler is at index.handler so that Lambda will look in the root of that ZIP archive for an index.js file. The Node.js Lambda runtime will then try to find a named export called handler and execute it as a function and pass it the event data as input.

If anything in these two properties are implemented incorrectly, AWS Lambda won’t be able to find your file and throw the “Lambda configuration error.” This can mean a typo on both sides, the file and directory names, and respective properties’ configuration.

Conclusion

Lambda errors aren’t always obvious, but most of them are usually not hard to fix – Lambda configuration error is not an exception, but the rule. The best you can do is to familiarize yourself with your IaC tool of choice. Understand how it finds your local Lambda source files, how it packages, and how it uploads them.

In the end, everything deployed to AWS will be defined in a CloudFormation template file-written by you or generated from your IaC tool-that points to an S3 bucket with a ZIP archive.

As a last resort, if you really don’t know what’s happening and are out of ideas on detecting or fixing this Lambda configuration error, try to find what template was uploaded to CloudFormation, and compare it with the content of the S3 bucket it points to.

Also published at: https://dashbird.io/blog/lambda-configuration-error/