Running aws-sam locally in macOS

This is the extension of article I wrote for Medium. Here is the post: Running AWS Lambda Locally in macOS

Assuming you are familiar with all the jargons of AWS, cloud and Serverless ecosystem, this post is targeted to show how to develop and test your Lambda functions locally.

The easiest way to set up application is through AWS console, I am not comfortable in crazy maze of AWS cloud formation templates. However, if you create an application and a function through AWS console, it creates one for you. So, go for it and don’t waste your time in correcting AWS templates.

First you need to install and if you already have one, upgrade the sam cli. It needs additional brew manager ‘tap’.

brew tap aws/tap

brew install aws-sam-cli


brew upgrade aws-sam-cli

You also need a working docker engine daemon in your local set up. Don’t forget!

Assuming you have some kind of local editors like VS Code, import the function to your local environment. Note: you may need to set up VS Code with AWS Toolkit extension and authenticated with a user profile.

To run a lambda function locally you need to call this in its simplest form from sam application root directory (where you have placed template.yaml).

sam local invoke

If it complains that it did not find the function, open template.yaml and add run configuration through “Code Lens” actions. You would see “add debug configuration” button within template.yaml.

But to run the lambda function successfully in local environment, you would need gcloud command utility to authorize your account for docker. Bizarre dependency from AWS team that they had to depend on a rival library. Well, if you don’t log in through gcloud, you will receive the following error. I was forced to install gcloud utility.

docker.credentials.errors.InitializationError: docker-credential-gcloud not installed or not available in PATH

After authentication, sam local invoke will run successfully. It will take some time to build docker image for the first time. But it will be a breezing fast on subsequent invocations.

If you need to invoke specific function you can do so by passing the command line arguments:

sam local invoke "<function name in template.yaml>" -e event.json

Please note the run configuration within VS Code has issues as of this writing. It always throws ‘Invalid (or missing) template file’ error.

So best option is to invoke sam application lambda through command line.

Please let me know, you all had success in your set-ups.

Happy coding!