# Debug your serverless application with AWS SAM
<a name="debug-application"></a>

After testing your application, you will be ready to debug any issues you’ve found. With the AWS SAM command line interface (CLI), you can locally test and debug your serverless application before uploading it to the AWS Cloud. Debugging your application identifies and fixes issues or errors in your application.

You can use AWS SAM to perform step-through debugging, which is a method of running code one line or instruction at a time. When you locally invoke a Lambda function in debug mode within the AWS SAM CLI, you can then attach a debugger to it. With the debugger, you can step through your code line by line, see the values of different variables, and fix issues the same way you would for any other application. You can verify whether your application is behaving as expected, debug what's wrong, and fix any issues, before going through the steps of packaging and deploying your application.

**Note**  
If your application includes one or more layers, when you locally run and debug your application the layers package is downloaded and cached on your local host. For more information, see [How layers are cached locally](serverless-sam-cli-layers.md#local-testing-with-layers).

**Topics**
+ [

# Locally debug functions with AWS SAM
](serverless-sam-cli-using-debugging.md)
+ [

# Pass multiple runtime arguments when debugging with AWS SAM
](serverless-sam-cli-using-debugging-additional-arguments.md)
+ [

# Validate your AWS SAM applications with CloudFormation Linter
](validate-cfn-lint.md)

# Locally debug functions with AWS SAM
<a name="serverless-sam-cli-using-debugging"></a>

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
<a name="serverless-sam-cli-using-aws-toolkits"></a>

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:
+ [AWS Toolkit for Visual Studio Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/)
+ [AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/)
+ [AWS Toolkit for JetBrains](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/)

There are a variety of 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 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-debugging.html)  | AWS Toolkit for Visual Studio Code | [Working with AWS Serverless Application](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps.html) in the AWS Toolkit for Visual Studio Code User Guide  | 
| AWS Cloud9 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-debugging.html)  | AWS Cloud9, with AWS Toolkit enabled1 |  [Working with AWS serverless applications using the AWS Toolkit](https://docs.aws.amazon.com/cloud9/latest/user-guide/serverless-apps-toolkit.html) in the *AWS Cloud9 User Guide*.  | 
| WebStorm | Node.js | AWS Toolkit for JetBrains2 |  [Running (invoking) or debugging a local function](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/invoke-lambda.html) in the *AWS Toolkit for JetBrains*  | 
| PyCharm | Python | AWS Toolkit for JetBrains2 |  [Running (invoking) or debugging a local function](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/invoke-lambda.html) in the *AWS Toolkit for JetBrains*  | 
| Rider | .NET | AWS Toolkit for JetBrains2 |  [Running (invoking) or debugging a local function](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/invoke-lambda.html) in the *AWS Toolkit for JetBrains*  | 
| IntelliJ | Java | AWS Toolkit for JetBrains2 |  [Running (invoking) or debugging a local function](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/invoke-lambda.html) in the *AWS Toolkit for JetBrains*  | 
| GoLand | Go | AWS Toolkit for JetBrains2 |  [Running (invoking) or debugging a local function](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/invoke-lambda.html) 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](https://docs.aws.amazon.com/cloud9/latest/user-guide/toolkit-welcome.html#access-toolkit) in the *AWS Cloud9 User Guide*.

1. 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](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/setup-toolkit.html) in the *AWS Toolkit for JetBrains*.

## Running AWS SAM locally in debug mode
<a name="serverless-sam-cli-running-locally"></a>

In addition to integrating with AWS Toolkits, you can also run AWS SAM in debug mode to attach to third-party debuggers like [ptvsd](https://pypi.org/project/ptvsd/) or [delve](https://github.com/go-delve/delve).

To run AWS SAM in debug mode, use commands [sam local invoke](sam-cli-command-reference-sam-local-invoke.md) or [sam local start-api](sam-cli-command-reference-sam-local-start-api.md) 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.

# Pass multiple runtime arguments when debugging with AWS SAM
<a name="serverless-sam-cli-using-debugging-additional-arguments"></a>

You may choose to pass additional runtime arguments with AWS SAM to inspect issues and troubleshoot variables more effectively. Doing this provides added control and flexibility to your debugging process, which can help you with customized runtime configurations and environments.

To pass additional runtime arguments when you're debugging your function, use the environment variable `DEBUGGER_ARGS`. This passes a string of arguments directly into the run command that the AWS SAM CLI uses to start your function.

For example, if you want to load a debugger like iKPdb at the runtime of your Python function, you could pass the following as `DEBUGGER_ARGS: -m ikpdb --ikpdb-port=5858 --ikpdb-working-directory=/var/task/ --ikpdb-client-working-directory=/myApp --ikpdb-address=0.0.0.0`. This would load iKPdb at runtime with the other arguments you’ve specified.

In this case, your full AWS SAM CLI command would be:

```
DEBUGGER_ARGS="-m ikpdb --ikpdb-port=5858 --ikpdb-working-directory=/var/task/ --ikpdb-client-working-directory=/myApp --ikpdb-address=0.0.0.0" echo {} | sam local invoke -d 5858 myFunction
```

You can pass debugger arguments to the functions of all runtimes.

# Validate your AWS SAM applications with CloudFormation Linter
<a name="validate-cfn-lint"></a>

 AWS CloudFormation Linter (cfn-lint) is an open-source tool that you can use to perform detailed validation on your CloudFormation templates. Cfn-lint contains rules that are guided by the CloudFormation resource specification. Use cfn-lint to compare your resources against those rules to receive detailed messages on errors, warnings, or informational suggestions. Alternatively, create your own custom rules to validate against. To learn more about cfn-lint, see [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) in the *CloudFormation GitHub repository*. 

 You can use cfn-lint to validate your AWS Serverless Application Model (AWS SAM) templates through the AWS SAM Command Line Interface (AWS SAM CLI) by running **sam validate** with the **--lint** option. 

```
sam validate --lint
```

 To customize cfn-lint behavior, such as creating custom rules or specifying validation options, you can define a configuration file. To learn more, see [Config File](https://github.com/aws-cloudformation/cfn-lint#config-file) in the *cfn-lint CloudFormation GitHub repository*. When you run **sam validate --lint**, cfn-lint behavior defined in your configuration file will be applied. 

## Examples
<a name="validate-cfn-lint-examples"></a>

### Perform cfn-lint validation on an AWS SAM template
<a name="validate-cfn-lint-examples-example1"></a>

```
sam validate --lint --template myTemplate.yaml
```

## Learn more
<a name="validate-cfn-lint-learn"></a>

 To learn more about the **sam validate** command, see [sam validate](sam-cli-command-reference-sam-validate.md).