Locally debug functions with AWS SAM - AWS Serverless Application Model
Using AWS ToolkitsRunning AWS SAM locally in debug mode

Locally debug functions with AWS SAM

You can use AWS SAM with a variety of AWS toolkits and debuggers to test and debug your serverless applications locally. Step-through debugging of your Lambda functions allows you to identify and fix issues in your application one line or instruction at a time in your local environment.

Some of the ways you can perform local step-through debugging includes setting breakpoints, inspecting variables, and executing function code one line at a time. Local step-through debugging tightens the feedback loop by making it possible for you to find and troubleshoot issues that you might run into in the cloud.

You can use AWS Toolkits to debug, and you can also run AWS SAM in debug mode. See the topics in this section for details.

Using AWS Toolkits

AWS Toolkits are integrated development environment (IDE) plugins that provide you with the ability to perform many common debugging tasks, like setting breakpoints, inspecting variables, and executing function code one line at a time. AWS Toolkits make it easier for you to develop, debug, and deploy serverless applications that are built using AWS SAM. They provide an experience for building, testing, debugging, deploying, and invoking Lambda functions that's integrated into your IDE.

For more information about AWS Toolkits that you can use with AWS SAM, see the following:

There are a variety AWS Toolkits that work with different combinations of IDEs and runtimes. The following table lists common IDE/runtime combinations that support step-through debugging of AWS SAM applications:

IDE Runtime AWS Toolkit Instructions for step-through debugging
Visual Studio Code

  • Node.js

  • Python

  • .NET

  • Java

  • Go

 AWS Toolkit for Visual Studio Code Working with AWS Serverless Application in the AWS Toolkit for Visual Studio Code User Guide
AWS Cloud9

  • Node.js

  • Python

 AWS Cloud9, with AWS Toolkit enabled1

Working with AWS serverless applications using the AWS Toolkit in the AWS Cloud9 User Guide.
WebStorm Node.js AWS Toolkit for JetBrains2

Running (invoking) or debugging a local function in the AWS Toolkit for JetBrains
PyCharm Python AWS Toolkit for JetBrains2

Running (invoking) or debugging a local function in the AWS Toolkit for JetBrains
Rider .NET AWS Toolkit for JetBrains2

Running (invoking) or debugging a local function in the AWS Toolkit for JetBrains
IntelliJ Java AWS Toolkit for JetBrains2

Running (invoking) or debugging a local function in the AWS Toolkit for JetBrains
GoLand Go AWS Toolkit for JetBrains2

Running (invoking) or debugging a local function in the AWS Toolkit for JetBrains

Notes:

  1. To use AWS Cloud9 to step-through debug AWS SAM applications, the AWS Toolkit must be enabled. For more information, see Enabling the AWS Toolkit in the AWS Cloud9 User Guide.

  2. To use the AWS Toolkit for JetBrains to step-through debug AWS SAM applications, you must first install and configure it by following the instructions found in Installing the AWS Toolkit for JetBrains in the AWS Toolkit for JetBrains.

Running AWS SAM locally in debug mode

In addition to integrating with AWS Toolkits, you can also run AWS SAM in "debug mode" to attach to third-party debuggers like ptvsd or delve.

To run AWS SAM in debug mode, use commands sam local invoke or sam local start-api with the --debug-port or -d option.

For example:

# Invoke a function locally in debug mode on port 5858
sam local invoke -d 5858 <function logical id>

# Start local API Gateway in debug mode on port 5858
sam local start-api -d 5858
Note

If you're using sam local start-api, the local API Gateway instance exposes all of your Lambda functions. However, because you can specify a single debug port, you can only debug one function at a time. You need to call your API before the AWS SAM CLI binds to the port, which allows the debugger to connect.