AWS SAM local – debugging Lambda and API Gateway with breakpoints demo


This new serverless world is great, but if you dive into it too fast – sometimes you end up getting caught up trying to get it all working, and forget to focus on having your local development environment running efficiently. This often costs developers time, and as a consequence it also costs the business money.

One of the things I see fairly often, is developers adopting AWS Serverless technologies because they know that’s what they should be doing (and everyone else is doing it), but they end up sacrificing their local development flows to do so – and the one that’s most obvious is running lambdas locally with breakpoints.

This post covers how to get local debugging working using breakpoints and an IDE from a fresh AWS SAM project using the Python3.6 runtime.

I’m using the Windows Subsystem for Linux and Docker on Windows.


Video Demo

There is a high level step-by-step below, but the video contains exact steps and a demo of this working using WSL and Docker for Windows.

Step by step

Assuming you’ve got the prerequisites above, the process of getting a new project set up and hooked up to your IDE is relatively straight forward.

1. Initialise a new python runtime project with:

$ sam init --runtime python3.6

2. Test we can run our API Gateway mock, backed by our lambda locally using:

$ sam local start-api

3. Hit our app in a browser at:

Screen Shot 2019-05-29 at 2.02.43 PM

4. Add the debugging library to requirements.txt


5. Import the debug library and have it listen on a debug port


import ptvsd

ptvsd.enable_attach(address=(‘’, 5890), redirect_output=True)

6. Build the changes to the app in a container using:

$ sam build --use-container

7. Set a breakpoint in your IDE

8. Configure the debugger in your IDE (Visual Code uses launch.json)

   "version": "0.2.0",
   "configurations": [
           "name": "SAM CLI Python Hello World",
           "type": "python",
           "request": "attach",
           "port": 5890,
           "host": "",
           "pathMappings": [
                   "localRoot": "${workspaceFolder}/hello_world",
                   "remoteRoot": "/var/task"

9. Start your app and expose the debug port using:

$ sam local start-api --debug-port 5890

10. Important: hit your endpoint in the browser

This will fire up a docker container that has the debug port exposed. If you attempt to start the debugger in your IDE before doing this, you will get a connection refused error.

11. Start the debugger in your IDE:

This should drop you into an interactive debugging session in your IDE. Great!


While adopting new technologies can be challenging and fun, it’s important that you keep your local development as efficient as possible so you can spend your time on what you do best: developing.

Consegna helps its partners transition from traditional development processes, to cloud development processes with minimal disruption to workflow. By demonstrating to developers that their day-to-day lives won’t change as much as they think, we find that widespread adoption and enthusiasm for the cloud is the norm, not the exception for developers in our customer engagements.