Step-through debugging Lambda functions locally - Amazon Serverless Application Model
Using Amazon ToolkitsRunning Amazon SAM locally in debug mode
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Step-through debugging Lambda functions locally

You can use Amazon SAM with a variety of Amazon toolkits and debuggers to test and debug your serverless applications locally.

For example, you can perform local step-through debugging of your Lambda functions by 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.

Using Amazon Toolkits

Amazon 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. Amazon Toolkits make it easier for you to develop, debug, and deploy serverless applications that are built using Amazon SAM. They provide an experience for building, testing, debugging, deploying, and invoking Lambda functions that's integrated into your IDE.

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

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

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

  • Node.js

  • Python

  • .NET

  • Java

  • Go

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

  • Node.js

  • Python

 Amazon Cloud9, with Amazon Toolkit enabled1

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

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

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

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

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

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

Notes:

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

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

Running Amazon SAM locally in debug mode

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

To run Amazon 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 Amazon SAM CLI binds to the port, which allows the debugger to connect.