How to connect VSCode Node debugger to local SAM

Question

I am trying to switch from the Serverless Framework to SAM for Lambda/API development. Serverless makes it very easy to debug locally using the serverless-offline plugin. I just start the plugin and attach my VSCode debugger. I can then set a breakpoint in any function/endpoint, request that endpoint using PostMan and my code pauses on the breakpoint.

SAM is far more convoluted and I am wondering if it even supports local debugging?

* I am invoking local SAM `sam local start-api`
* I can hit my local Lambda API endpoint using PostMan to GET `http://127.0.0.1:3000/`
* When I restart local SAM in debug mode `sam local start-api -d 5858` and attach from VSCode and reissue my GET request VSCode opens `\var\runtime\index.js` and stops on the first line of code. When I resume from there my breakpoint in my function is not hit but the API request completes.

launch.json

```json
    {
      "name": "Attach to SAM CLI",
      "type": "node",
      "request": "attach",
      "address": "127.0.0.1",
      "port": 5858,
      "sourceMaps": true,
      "localRoot": "${workspaceFolder}/src",
      "remoteRoot": "/var/task",
      "protocol": "inspector",
      "stopOnEntry": false
    }```

Answer

Hello again!

I found another document that you'll want to check out as well and I believe this is actually going to be a key document you'll want to check out:

https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/debug-apigateway.html

This will show you how to configure the locally running API Gateway, provide payloads, and how to run and invoke the API as well.

Answer

Hello,

You can use AWS SAM to debug and test applications on your local machine and it supports Microsoft Visual Studio Code debugging via the AWS Toolkit for VSCode.

You’ll want to read through the steps fully at the following link[[1]], but I’ll go ahead and list the steps below:

* Be sure that your system meets the required prerequisites specified in Installing the AWS Toolkit for Visual Studio Code. Be sure to view the optional section which mentions installing Docker. Docker is required for local debugging of Lambda functions.
* Install the AWS Serverless Application Model (AWS SAM) command line interface (CLI) and its prerequisites. See AWS SAM CLI in the setup prerequisites. If Visual Studio Code is open when you perform these installations, you might need to close and reopen the editor.
* Identify your default AWS Region in your AWS config file. For more information, see Configuration and credential file settings in the AWS Command Line Interface User Guide. If Visual Studio Code is open when you update your config file, you might need to close and reopen the editor.
* After installing your language SDK, be sure to configure your toolchain. You’ll want to follow the specific steps for Node.js in your case.
* To ensure that you can access the CodeLens feature in AWS SAM template files, install the YAML language support VS Code extension.

After following the steps in the Assumptions and prerequisites section, continue on to the IAM permissions for serverless applications[[2]] page just to be complete and sure we’re not missing anything as far as permissions.

Since you already have a pre-existing SAM application you’ll just want to open up the project[[3]], no need to create a new one.

Now comes the debugging portion, and there’s two method you can follow. You can run and debug from the template file[[4]], or you can run and debug the Lambda function directly from code[[5]]. The important item here is making sure all the previous steps have been followed and have Docker installed and running.

You can setup advanced configuration for debugging as well[[6]] and there is some Docker items you’ll want to review and some caveats for Node.js in the pathMappings section. Just wanted to mention those since I caught them and wanted to be sure you review them. I found a deeper dive into this configuration file with some tips here also[[7]].

I also wanted to be sure I share a video tutorial to give an overview of the usage a bit if it helps illustrate things a bit more. You can check out the video here[[8]]. This second video is a bit of a hidden gem I like from re:Invent 2020[[9]] and I linked directly to the timestamp discussing a bit of local testing using just the SAM CLI. The full video has a lot of knowledge all contained into a single spot, so thought I’d share it just to be complete.

For more specific bugs or troubleshooting with the SAM CLI you're facing, the GitHub page is a great spot to check out [[10]]. The team and community on there may have some related deeper items they can help point you towards or a pre-existing answer on the site.

[[1]] Working with serverless applications - Assumptions and prerequisites - https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps.html#serverless-apps-assumptions

[[2]] Working with serverless applications - IAM permissions for serverless applications - https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps.html#serverless-apps-permissions

[[3]] Working with serverless applications - Opening a serverless application (local) - https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps.html#serverless-apps-open

[[4]] Working with serverless applications - Running and debugging a serverless application from template (local) - https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps.html#serverless-apps-debug

[[5]] Running and debugging Lambda functions directly from code - https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-no-template.html

[[6]] Configuration options for debugging serverless applications - https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html

[[7]] https://aws.amazon.com/blogs/developer/introducing-launch-configurations-support-for-sam-debugging-in-the-aws-toolkit-for-vs-code/

[[8]] https://www.youtube.com/watch?v=FINV-VmCXms

[[9]] https://youtu.be/wPk9OEmxJhQ?t=811

[[10]] https://github.com/aws/aws-sam-cli

How to connect VSCode Node debugger to local SAM

Relevant content