Application Debugging

Debugging Node.js AWS Lambda Functions using ServerlessDebugger

Baris Kaya
3 mins read

While developing your serverless functions, debugging may become cumbersome because you are now dealing with a black box compute service that provides log lines after the execution is finished. You might get lost in the logs. Redeploying and trying again with different parameters over and over can be a tedious process. AWS SAM CLI’s local debugging capabilities are really helpful at this point. However, simulating the AWS Lambda environment in your local might not be what you want always. Sometimes we need to debug our Lambda functions in their native environment with all of the permissions, VPC’s, triggers, and the stuff. Only in this way, you can “re-play” the exact behavior of your AWS Lambda functions.

As a solution to this problem, Thundra released the ServerlessDebugger which is the most native debugging experience ever for AWS Lambda! You will be able to debug Lambda functions as they run in their native cloud environment, with all the traditional debugging capabilities like tracking changes in local variables, updating them on the fly, and putting breakpoints.

Using ServerlessDebugger with Node.js AWS Lambda Functions

To demonstrate how you can use the ServerlessDebugger with Node.js AWS Lambda functions, we will use a fully serverless blog site application. The architecture of this serverless blog site application is fairly simple. Basically, a static website served through S3 contains the frontend logic of our blog site application. All the operations made through the application; like creating a new blog post, viewing a blog post, or deleting a blog post invoke the corresponding Lambda function through the API Gateway.


We will first create a blog post in our blog site application, then we will enable ServerlessDebugger for one of the Lambda functions in our system which is blog-site-dev-deleteBlogPost. This Lambda function is responsible for the deletion of a blog post in our system. To invoke this Lambda function we will delete the blog post that we are going to add and will debug this invocation in our local IDE which is VSCode for this particular example.

blog-site-dev-deleteBlogPost function in AWS Console

Firstly, let's add a new blog post in Add Blog tab of our blog site application:


Then, we can enable the AWS Lambda Debugger feature for the blog-site-dev-deleteBlogPost by adding the thundra_agent_lambda_debugger_auth_token environment variable. This will tell the Thundra agent inside our lambda function to start ServerlessDebugger using the authentication token specified in the environment variable.

adding our authentication token using the environment variables

Now, we can turn back to our blog site application to delete the blog post that we have added above to invoke the blog-site-dev-deleteBlogPost Lambda function and debug the invocation in the VSCode. To delete the blog post, just click the trash button in the action column below.


After having invoked the blog-site-dev-deleteBlogPost, we can now open the VSCode and open our blog site application project and start the ServerlessDebugger.


When the connection is made, our Lambda function blog-site-dev-deleteBlogPost will hit the breakpoint that we put as in below:


From now on, you can debug this invocation just like debugging a local Node.js application. You can put breakpoints on the fly, change the values of the local variables, add expressions to watch, and so on.  To learn more about ServerlessDebugger you can check out how to get started in the documentation.

How it works in the background

To make debugging possible on the AWS Lambda environment, ServerlessDebugger provides a proxy-based solution that sets up a secure bridge between the AWS Lambda environment and your debugger on IDE with a web socket communication. In this way, you can debug your applications like you could debug any code that you host on your computer with native debug action. We are calling this bridge a “broker” which is basically a proxy for the communication between your AWS Lambda function and your IDE.

Another important point is that ServerlessDebugger only lets one invocation start a debugging session. This way while you are debugging an invocation of your Lambda function, other invocations will start and finish normally instead of waiting for a debugger to connect. You should also be aware that you might need to increase your function’s timeout value to prevent your invocation from a timeout while you are debugging.



As a developer working with serverless functions, I was really having a hard time understanding the behavior of Lambda functions from time to time with logs. Writing a new log statement, redeploying the function, and checking the logs again was very time-consuming while debugging AWS Lambda functions. I’m proud to be part of such innovation with ServerlessDebugger making it possible to debug AWS Lambda functions as if they were running locally. We have developed a VSCode plugin for Node.js and Python functions.

You can start your native debugging experience by signing up for ServerlessDebugger for free. Start following us on Twitter to catch up with our latest announcements, and join our discord community for instant communication.