Debugging with Dashbird: Lambda Configuration Error

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
    Type: AWS::Serverless::Function
      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.


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.

well architected insights lens

If you want to know pinpoint where things are going wrong, our Well-Architected Insights feature will give you a quick and easy understanding of how your current settings are impacting your whole system, what exactly is affected, and what to do about it. Try it out for yourself.

Further reading:

AWS Lambda Error Handling Step Functions

AWS Lambda Logging: Error Types

AWS Lambda configuration error

Read our blog

Introducing easy custom event monitoring for serverless applications.

Today we are excited to announce scheduled searches – a new feature on Dashbird that allows you to track any log event across your stack, turn it into time-series metric and also configure alert notifications based on it.

Why and How to Monitor Amazon OpenSearch Service

One of the most vital aspects to monitor is the metrics. You should know how your cluster performs and if it can keep up with the traffic. Learn more about monitoring Amazon OpenSearch Service.

Why and How to Monitor AWS Elastic Load Balancing

Dashbird recently added support for ELB, so now you can keep track of your load balancers in one central place. It comes with all the information you expect from AWS monitoring services and more!

More articles

Made by developers for developers

Dashbird was born out of our own need for an enhanced serverless debugging and monitoring tool, and we take pride in being developers.

What our customers say

Dashbird gives us a simple and easy to use tool to have peace of mind and know that all of our Serverless functions are running correctly. We are instantly aware now if there’s a problem. We love the fact that we have enough information in the Slack notification itself to take appropriate action immediately and know exactly where the issue occurred.

Thanks to Dashbird the time to discover the occurrence of an issue reduced from 2-4 hours to a matter of seconds or minutes. It also means that hundreds of dollars are saved every month.

Great onboarding: it takes just a couple of minutes to connect an AWS account to an organization in Dashbird. The UI is clean and gives a good overview of what is happening with the Lambdas and API Gateways in the account.

I mean, it is just extremely time-saving. It’s so efficient! I don’t think it’s an exaggeration or dramatic to say that Dashbird has been a lifesaver for us.

Dashbird provides an easier interface to monitor and debug problems with our Lambdas. Relevant logs are simple to find and view. Dashbird’s support has been good, and they take product suggestions with grace.

Great UI. Easy to navigate through CloudWatch logs. Simple setup.

Dashbird helped us refine the size of our Lambdas, resulting in significantly reduced costs. We have Dashbird alert us in seconds via email when any of our functions behaves abnormally. Their app immediately makes the cause and severity of errors obvious.