How do debug AWS SAM Local

Is there any guidance available on how to configure debugging when running AWS Lambda functions locally using AWS SAM Local?


there is no guidance for it (no special support is provided), but the instructions for VSCode ( should work for webstorm, too: you have to start the app in the way described in the doc and then create a run configuration of type "Attach to Node.js/Chrome", with port matching the port you pass to your app as --debug-port.

Note: when using Node.js versions < 7 (e.g. Node.js 4.3 and Node.js 6.10) choose the Node.js option, for Node.js versions including and above 7 (e.g. Node.js 8.10) use Chrome


Heads up link is dead


I would like to debug my python lambda function the same way mentioned. What do you recommend?


All I think about this fact is that I pay a good deal for this and VS code is free.  Ridiculous there isn't a Youtube video for by JB 
"Configuring  Webstorm for local AWS lamba with node"
"Configuring  Webstorm for local AWS lamba with Java"
... And if those videos do exist, they need to find a way to promote or SEO them better, 2 days looking for this page, a page with links and not a simple clear answer.


did you try using AWS Toolkit for WebStorm for running/debugging AWS Lambda functions as suggested in
Also, if you need running AWS SAM locally in debug mode, please follow the instructions at and then create a run configuration of type Attach to Node.js/Chrome, with port matching the port you pass to your app as --debug-port (-d).


STEP BY STEP GUIDE for Local Debugging with Node AWS Lambdas
For this to work It will be assumed you figured out how to make
template.yaml and event.json file (basically holds the json event that would go to your lambda).  And that you have installed and configured the AWS toolkit.

1. On the top menu click on :: "Run > Edit Configurations"

2. Click the "+" at the top right corner

3. Chose "AWS Lambda Local" from the drop down

( Look and the three tabs at the top.... Configuration, Sam CLI, AWS connection )
Go to the AWS Connection tab, it should already be filled out if you added the AWS toolkit with creds

Go to the Configuration tab, chose the From Template radio option,
First chose the radio button From Template, then navigate to a template.yaml file (assumed this was created)
skip down to where it says Input, choose the File radio button and select your event.json file (assumed this was created)

4. Click apply

5. To run it, On the top menu click on :: "Run > Debug[local] ............" it should be the second option or so

6. If you have any issues with npm not building , try going back to "edit configurations" , the "SAM CLI" tab and selecting "Build function inside a container"

helpful links :


In Sam there is an option to run an api gateway by passing the cdk stack to Sam. With this you can call the lambda functions by means of a local apigateway/path.

In VsCode it is possible to start a debugger pointing to a port and provide the source of the lambda without having to declare events or declaring a lambda yaml file as it is part of the cdk stack. Does IntelliJ or webstorm have similar functionality?


Could you clarify what VSCode functionality you refer to? What does the launch configuration look like?


Ofcourse, below is a sample launch configuration from VsCode

"name": "Attach to SAM CLI demand",
"type": "node",
"request": "attach",
"address": "localhost",
"port": 9002,
"localRoot": "${workspaceFolder}/resources/lambda/demand",
"remoteRoot": "/var/task",
"protocol": "inspector",
"stopOnEntry": false

The above allows to connect to a debugger by means of a port instead of configuring the specific lambda and provide a lambda template as previously described on this chain. Similar functionality should exist in jetbrain products.

I see; you can use Attach to Node.js/Chrome configuration for this, I believe, please see above


Could anyone help here?
cc: William Hammock  I tried your steps above and feel I am very close to running locally. The only problem is that it's not able to read from my input file.
inputfile contents:

  "eventType": "BILLING",
  "quote": {
    "policyNumber": "H3i",
    "jurisdiction": "CA",
    "transactionType": "NEW_BUSINESS",
    "billing": {
      "method": "CREDIT_CARD",
      "downPayment": {
        "amount": 150
    "totalPolicyPremium": "100.00"


Invoking handler.handler (nodejs18.x)
Local image is up-to-date
Using local image:

Mounting /Users/n1595496/workspace/property/.aws-sam/build/ValidationsLambda as /var/task:ro,delegated, inside runtime container
START RequestId: 33158fbf-44ec-456f-b184-8094f807cdbf Version: $LATEST
{"level":"FATAL","awsRegion":"us-east-1","context":{"requestId":"ed2a6b97-e165-4173-8427-d9db33feb111","awsRequestId":"33158fbf-44ec-456f-b184-8094f807cdbf","functionName":"ValidationsLambda","functionVersion":"$LATEST","invokedFunctionArn":"arn:aws:lambda:us-east-1:012345678912:function:ValidationsLambda","memoryLimitInMB":"128","logGroupName":"aws/lambda/ValidationsLambda","logStreamName":"$LATEST"},"env":"local","error":{"type":"nm","message":"Platform Error : [UNKNOWN]: Cannot read properties of undefined (reading 'eventType')","stack":"nm: Platform Error : [UNKNOWN]\n    at onError (/var/task/handler.js:105:34719)\n    at s (/var/task/handler.js:105:42645)\n    at rZ (/var/task/handler.js:105:42843)\n    at v (/var/task/handler.js:105:43066)\n    at /var/task/handler.js:105:43100\ncaused by: TypeError: Cannot read properties of undefined (reading 'eventType')\n    at MI (/var/task/handler.js:124:69904)\n    at before (/var/task/handler.js:124:72588)\n    at s (/var/task/handler.js:105:42380)","details":[{"code":"UNKNOWN","description":"An unexpected error occurred.","status":500}],"name":"nm"},"status":500,"details":[{"code":"UNKNOWN","description":"An unexpected error occurred."}],"message":"Error handling middleware returned an error response"}
END RequestId: 33158fbf-44ec-456f-b184-8094f807cdbf
REPORT RequestId: 33158fbf-44ec-456f-b184-8094f807cdbf    Init Duration: 1.13 ms    Duration: 4592.15 ms    Billed Duration: 4593 ms    Memory Size: 128 MB    Max Memory Used: 128 MB    





Please sign in to leave a comment.