How to Build, Run and Debug AWS Lambda function locally using AWS SAM CLI

In this piece, I will guide you to build, run and debug AWS Lambda function locally using AWS SAM CLI

1. Install AWS SAM CLI

You will need AWS SAM CLI installed on your machine in order to build, run, and deploy AWS Lambda functions.

Please follow this link to Install SAM CLI on your machine.

How to use AWS SAM to create and deploy AWS resources is out of the scope of this document. Please refer AWS SAM documentation to learn more about it.

2. Create a project directory and add the AWS SAM template.yaml specification

Folder structure

I have two lambda functions defined in this project in src directory. Each function is having its own folder and index.js file. Also I have added function-wise unit tests in the separate tests directory.

SAM template.yaml

The template.yaml file is as shown above. Please note the resource names of two functions i.e. MyFirstLambdaFunction and MySecondLambdaFunction. We will need these resource names while invoking the functions locally.

Also, note the Handler values for each function. The format for Handler value is PathOfHandlerFile.HandlerName. Here the path of my file containing lambda handler is src/MyLambdaFunction/index and handler name in index.js is handler. For the second function the path differs.

For the sake of simplicity, this function only returns text as a response.

3. Build the Lambda function locally

Before you start to build your function locally, make sure the Docker daemon is running on your system. If the docker daemon is not running then SAM build will not work.

Now, start the build by the following command. Make sure you are at project root while running this command. This command will build all lambda functions present in the project directory.

sam build

You can use use-container flag to build your project inside docker container. This is helpful when you have platform-specific dependencies(in my case it was bcrypt library) which cause error after deploying function on AWS.

sam build --use-container

Please note that use-container command will download nodeJs build docker image which is a huge image ( ~1.6GB) one time. Select this flag only when needed.

If you use this flag and a new version of nodeJs build docker image is available then it starts to download the new image automatically. You can avoid this by using skip-pull-image flag. This will not download the new image.

sam build --use-container --skip-pull-image

Once the build is successful you should see something like this.

Successful build

4. Run and debug function.

Before you start debugging add the following content in launch.json file in VS Code. This will allow us to add breakpoints and debug the function execution.

Now run the function locally by the following command. Here, we are specifying the function resource name in quotes. This is the resource name from template.yaml mentioned in Step 2 above.

sam local invoke "MyFirstLambdaFunction" --debug-port=5858

This will one time download the docker image which is relatively small (~350 MB). To avoid pulling a new image every time you can use skip-pull-image flag as mentioned in Step 3.

After this, the debugger will start listening on port 5858 and wait for the debugger to get attached.

Debugger attached

Now, attach debugger from VS Code debugging menu by clicking the green arrow.

If you have added a breakpoint in the code, you can find your function execution has halted at the breakpoint as shown below.

Execution halted at the breakpoint

Once you run over the breakpoint you will see function response in the console.

Response from lambda

I hope this was somewhat helpful.

Happy Coding :)