Remote Debugging

Lambda Remote Debugging lets you use breakpoints, inspect variables, and step through your Lambda function code locally within VS Code. It is supported for Python, Node.js, and Java, and works with SAM-based or standalone Lambda projects.

This guide describes how to use the AWS Toolkit for VS Code to debug Lambda functions running in LocalStack. This new integration enables interactive, IDE-native debugging for Python, Node.js, and Java Lambda functions with minimal setup.

• One-click remote automatic debugger configuration and injection via the AWS Toolkit for VS Code
• Automatic Timeout Management
• Support for Python, Node.js, and Java runtimes

• Install the lstk CLI
• VS Code (>= v1.83.0)
• AWS Toolkit for VS Code (>= v3.74)
• LocalStack Toolkit for VS Code (>= v1.2.0)
• Docker
• A valid LocalStack Auth Token. Sign up for a free LocalStack account.
• A valid auth token
• VS Code running on the same machine as LocalStack (container-based setups like Kubernetes are not yet supported).

The following setup creates the required ~/.aws/config and ~/.aws/credentials entries and ensures LocalStack runs with your active license.

1. Install AWS Toolkit and LocalStack Toolkit from the VS Code Marketplace.
2. Install the latest version of the AWS SAM CLI for using the AWS Application builder functionality in the AWS Toolkit.
3. Run the LocalStack: Run Setup Wizard from the Command Palette. (This sets your auth token and configures the localstack AWS profile.)

4. Start LocalStack using the status bar or the command Start LocalStack.
5. Switch your AWS profile in the status bar to profile:localstack.

You can debug either your own Lambda function or our sample project.

1. Open the AWS Explorer in VS Code.

2. To install the sample application, select the ... menu in the AWS Explorer view and choose Create application with Serverless template.

3. Choose the “Process SQS Records with Lambda” sample.

4. Select a runtime (Python, Node.js, or Java).

5. Complete the wizard to generate the project.

1. Deploy the function:

   • Go to Application Builder view
   • Click Deploy SAM Application (cloud icon)

• Follow the wizard to deploy to LocalStack

2. Open Remote Invoke Configuration:

   • In AWS Explorer, right-click your deployed Lambda function
   • Select Invoke Remotely

3. Enable Remote Debugging:

   • In the configuration view, check Remote debugging

• If prompted, provide the event input (e.g., SQS sample event)

4. Set Breakpoints and Debug:

   • Open your Lambda handler source file
   • Set breakpoints in the margin
   • Click Remote Invoke

Your Lambda function will execute in LocalStack and pause at your breakpoint. You can inspect variables, step through code, and continue execution.

To enable source-level debugging for TypeScript:

1. Build your TypeScript Lambda with source maps enabled:

 tsc --sourceMap true

2. Ensure the compiled .js and .map files are present in the deployment package.
3. Open the .ts source file in VS Code, set breakpoints, and proceed as with other runtimes.

If you receive the following error message:

UnsupportedLocalStackVersion: Your current LocalStack version does not support Lambda remote debugging. Update LocalStack and check your license.

Here’s how to fix it:

1. Make sure you are running LocalStack for AWS >= v4.8.0

   docker pull localstack/localstack-pro:latest

2. Ensure your auth token is valid and has an assigned license.

   • You can re-run the LocalStack Setup Wizard in VS Code to verify.
   • Or log into app.localstack.cloud and check your token and license status.

Should downloading the Lambda function code fail, here’s how to fix it:

• Disable DNS rebind protection (see LocalStack DNS docs)
• Use 127.0.0.1 instead of localhost.localstack.cloud (Automatic setup)
  • Run the LocalStack: Configure AWS Profile "localstack" command from the VS Code Command Palette which will auto-configure the correct endpoint.
• Use 127.0.0.1 instead of localhost.localstack.cloud (Manual setup)
  • Set LOCALSTACK_HOST=127.0.0.1:4566 in ~/.localstack/default.env
  • Update your endpoint_url in your localstack profile located in ~/.aws/config

Lambda Debug Mode is a preview feature in LocalStack designed to enhance your Lambda debugging workflows. This feature provides an optimized environment for debugging Lambda functions, ensuring that you have the necessary tools and flexibility to troubleshoot effectively.

• Automatic Timeout Management: Integrates with API Gateway to prevent Lambda function timeouts, giving developers ample time to connect remote debuggers and inspect the function’s behavior.
• Multi-Function Debugging: Supports debugging multiple Lambda functions concurrently.

To enable Lambda Debug Mode, set the LAMBDA_DEBUG_MODE environment variable as shown below:

[[containers]]
type = "aws"
env  = ["lambda-debug"]

[env.lambda-debug]
LAMBDA_DEBUG_MODE = "1"
LAMBDA_DOCKER_FLAGS = "-p 19891:19891"

lstk start

When enabled, Lambda Debug Mode automatically adjusts timeouts to accommodate debugging needs:

• Lambda Container Startup Timeout: Provides additional time for debugger connection during container creation.
• Lambda Execution Timeout: Extends the execution window, allowing for in-depth remote debugging.
• API Gateway-Lambda Integration Timeout: Increases timeout settings to avoid premature terminations.

For further customization, you can use a configuration file. Specify the path to this file with the LAMBDA_DEBUG_MODE_CONFIG_PATH environment variable, ensuring the file is mounted into the LocalStack container. Manually setting LAMBDA_DOCKER_FLAGS is unnecessary when using this configuration.

Here is an example of mounting a debug_config.yaml in your LocalStack container to start your Debug Mode:

[[containers]]
type    = "aws"
env     = ["lambda-debug-advanced"]
volumes = ["/path/to/debug-config.yaml:/tmp/lambda_debug_mode_config.yaml"]

[env.lambda-debug-advanced]
LAMBDA_DEBUG_MODE = "1"
LAMBDA_DEBUG_MODE_CONFIG_PATH = "/tmp/debug_config.yaml"

lstk start

1
services:
2
  localstack:
3
    container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}"
4
    image: localstack/localstack-pro
5
    ports:
6
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
7
      - "127.0.0.1:4510-4559:4510-4559"  # external services port range
8
      - "127.0.0.1:443:443"              # LocalStack HTTPS Gateway (Pro)
9
    environment:
10
      # LocalStack configuration: https://docs.localstack.cloud/references/configuration/
11
      - DEBUG=${DEBUG:-0}
12
      - LAMBDA_DEBUG_MODE=1
13
      - LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/debug_config.yaml
14
    volumes:
15
      - "./debug_config.yaml:/tmp/debug_config.yaml"
16
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
17
      - "/var/run/docker.sock:/var/run/docker.sock"

Any change to the configuration file on your local filesystem would be automatically picked by the LocalStack container. After debugging a Lambda function, its associated container will automatically stop.

The configuration file should contain a functions block where you can define debug settings for each specific Lambda function ARN.

This example configures Lambda Debug Mode to use port 19891 for the remote debugger.

1
functions:
2
  arn:aws:lambda:eu-central-1:000000000000:function:func-one:
3
    debug-port: 19891

In this example, the automatic timeout handling feature is disabled for the specified Lambda function, enforcing the predefined timeouts instead.

1
functions:
2
  arn:aws:lambda:eu-central-1:000000000000:function:func-one:
3
    debug-port: 19891
4
    enforce-timeouts: true

Specifying an unqualified Lambda ARN in the configuration is equivalent to specifying the ARN with the $LATEST version qualifier.

1
functions:
2
  arn:aws:lambda:eu-central-1:000000000000:function:func-one:$LATEST:
3
    debug-port: 19891

To debug multiple Lambda functions simultaneously, assign a different debug port to each function. Note that this configuration affects the container’s internal debugger port as well, so the debugger port must be set accordingly.

1
functions:
2
  arn:aws:lambda:eu-central-1:000000000000:function:func-one:
3
    debug-port: 19891
4
  arn:aws:lambda:eu-central-1:000000000000:function:func-two:
5
    debug-port: 19892

You can also debug different versions of the same Lambda function by assigning unique ports to each version.

1
functions:
2
  arn:aws:lambda:eu-central-1:000000000000:function:func-one:1:
3
    debug-port: 19891
4
  arn:aws:lambda:eu-central-1:000000000000:function:func-two:2:
5
    debug-port: 19892

• Debugging Python Lambda functions
• Debugging JVM Lambda functions
• Debugging Node.js Lambda functions

Lambda functions debugging used to be a difficult task. LocalStack changes that with the same local code mounting functionality that also helps you to iterate quickly over your function code.

First, make sure that LocalStack is started with the following configuration (see the Configuration docs for more information):

[[containers]]
type = "aws"
env  = ["lambda-debug"]

[env.lambda-debug]
LAMBDA_DOCKER_FLAGS = "-p 19891:19891"

lstk start

For providing the debug server, we use debugpy inside the Lambda function code. In general, all you need is the following code fragment placed inside your handler code:

1
import debugpy
2
debugpy.listen(("0.0.0.0", 19891))
3
debugpy.wait_for_client()  # blocks execution until client is attached

For extra convenience, you can use the wait_for_debug_client function from our example. It implements the above-mentioned start of the debug server and also adds an automatic cancellation of the wait task if the debug client (i.e. VSCode) doesn’t connect.

1
def wait_for_debug_client(timeout=15):
2
    """Utility function to enable debugging with Visual Studio Code"""
3
    import time, threading
4
    import sys, glob
5
    sys.path.append(glob.glob(".venv/lib/python*/site-packages")[0])
6
    import debugpy
7

8
    debugpy.listen(("0.0.0.0", 19891))
9
    class T(threading.Thread):
10
        daemon = True
11
        def run(self):
12
            time.sleep(timeout)
13
            print("Canceling debug wait task ...")
14
            debugpy.wait_for_client.cancel()
15
    T().start()
16
    print("Waiting for client to attach debugger ...")
17
    debugpy.wait_for_client()

For attaching the debug server from Visual Studio Code, you need to add a run configuration.

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "name": "Python: Remote Attach",
6
            "type": "python",
7
            "request": "attach",
8
            "connect": {
9
                "host": "localhost",
10
                "port": 19891
11
            },
12
            "pathMappings": [
13
                {
14
                    "localRoot": "${workspaceFolder}",
15
                    "remoteRoot": "."
16
                }
17
            ]
18
        }
19
    ]
20
}

In the next step we create our function. In order to debug the function in Visual Studio Code, run the preconfigured remote debugger, which will wait about 15 seconds as defined above, and then invoke the function. Make sure to set a breakpoint in the Lambda handler code first, which can then later be inspected.

The screenshot below shows the triggered breakpoint with our 'Hello from LocalStack!' in the variable inspection view:

Due to the ports published by the lambda container for the debugger, you can currently only debug one Lambda at a time. Due to the port publishing, multiple concurrently running lambda environments are not supported.

Please be aware that remote debugging in PyCharm is only available in the Professional version.

You do not need to change the LAMBDA_DOCKER_FLAGS when debugging with PyCharm Professional.

You can follow the steps in the official docs, which will come down to:

• Create a debug configuration with the IDE host name localhost and the debug port 19891.
• Add path mapping with your project files on the host and map it to the remote directory /var/task.
• Copy the pip install command, and make sure to install the correct pydevd-pycharm version for your PyCharm IDE.

PyCharm provides its own debugging package, called pydevd-pycharm. Essentially, you will add the following code to your lambda:

import pydevd_pycharm
pydevd_pycharm.settrace('host.docker.internal', port=19891, stdoutToServer=True,
                            stderrToServer=True)

The host.docker.internal is a special DNS name by Docker and will make sure that the lambda running in the docker can connect to PyCharm running on your Localhost.

You can use the wait_for_debug_client and add it to your lambda (please adapt the path to your venv directory if necessary):

def wait_for_debug_client():
    """Utility function to enable debugging with PyCharm"""
    import sys, glob
    # enter the correct path here to your venv (where pydev_pycharm is installed
    my_venv = "venv/lib/python*/site-packages"
    sys.path.insert(0, glob.glob(my_venv)[0])
    import pydevd_pycharm
    # host.docker.internal should resolve to the host
    # see also: https://docs.docker.com/desktop/networking#use-cases-and-workarounds-for-all-platforms
    pydevd_pycharm.settrace('host.docker.internal', port=19891, stdoutToServer=True,
                            stderrToServer=True)

In the next step we create our function. In order to debug the function in PyCharm set a breakpoint in your function, run the Remote Debug configuration and then invoke the function.

To create the Lambda function, you just need to take care of two things:

1. Deploy the function via an S3 Bucket. You need to use the magic variable hot-reload as the bucket name.
2. Set the S3 key to the path of the directory your lambda function resides in. The handler is then referenced by the filename of your lambda code and the function in that code that should be invoked.

Using the AWS CLI, this would be:

lstk aws lambda create-function --function-name my-cool-local-function \
    --code S3Bucket="hot-reload",S3Key="$(pwd)/" \
    --handler handler.handler \
    --runtime python3.13 \
    --timeout 150 \
    --role arn:aws:iam::000000000000:role/lambda-role

We can quickly verify that it works by invoking it with a simple payload:

lstk aws lambda invoke --function-name my-cool-local-function \
    --cli-binary-format raw-in-base64-out \
    --payload '{"message": "Hello from LocalStack!"}' \
    output.txt

Set LAMBDA_DOCKER_FLAGS to export the 5050 (you can use any other port of your choice) port which your IDE debugger will connect to.

services:
  localstack:
    ...
    environment:
      ...
      - LAMBDA_DOCKER_FLAGS=-p 127.0.0.1:5050:5050

When creating your Lambda function, set the _JAVA_OPTIONS environment variable like so:

lstk aws lambda create-function --function-name debugfunc \
    --zip-file fileb://java-handler.zip \
    --handler myindex.handler \
    --runtime java8.al2 \
    --timeout 150 \
    --role arn:aws:iam::000000000000:role/lambda-role \
    --environment '{"Variables": {"_JAVA_OPTIONS": "-Xshare:off -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0.0.0.0:5050"}}'

Note the suspend=y option here, it will delay code execution until the debugger is attached to the debugger server. If you want to change that, simply switch to suspend=n.

By default the runtime environment for Java will set -Xshare: on, so we’ll have to disable it here again. Your IDE might show you the listen address as *:5050, but please note that this only works for Java 9+.

Open the Run/Debug Configurations window and create a new Shell Script with the following content:

while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done

This shell script should simplify the process a bit since the debugger server is not immediately available (only once Lambda container is up).

Then create a new Remote JVM Debug configuration and use the script from above as a Before launch target:

Now to debug your Lambda function, simply click on the Debug icon with Remote JVM on LS Debug configuration selected, and then invoke your Lambda function.

The debugger can also act as a server by changing the drop-down “Debugger mode” to “Listen to remote JVM”. In this case you should not set LAMBDA_DOCKER_FLAGS since the port will be exposed on your host instead of the Lambda container. Compared to the previous setup the “Wait Remote Debugger Server” run configuration should also be removed and instead tick the mark at “Auto restart” after switching to the “Listen to remote JVM” mode.

For the Lambda function you will have to adjust the environment variable to "_JAVA_OPTIONS": "-Xshare:off -agentlib:jdwp=transport=dt_socket,server=n,address=172.17.0.1:5050,suspend=y,onuncaught=n". Notice the address=172.17.0.1:5050. Here we tell the Lambda function to connect to port 5050 on 172.17.0.1. When using Docker desktop you might have to set this to address=host.docker.internal:5050 instead.

Make sure you installed the following extensions:

• Language Support for Java(TM) by Red Hat
• Debugger for Java

Add a new task by creating/modifying the .vscode/tasks.json file:

1
{
2
    "version": "2.0.0",
3
    "tasks": [
4
        {
5
          "label": "Wait Remote Debugger Server",
6
          "type": "shell",
7
          "command": "while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done; sleep 1;"
8
        }
9
    ]
10
}

Create a new launch.json file or edit an existing one from the Run and Debug tab, then add the following configuration:

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "type": "java",
6
            "name": "Remote JVM on LS Debug",
7
            "projectRoot": "${workspaceFolder}",
8
            "request": "attach",
9
            "hostName": "localhost",
10
            "preLaunchTask": "Wait Remote Debugger Server",
11
            "port": 5050
12
        }
13
    ]
14
}

Now to debug your lambda function, click on the Debug icon with Remote JVM on LS Debug configuration selected, and then invoke your lambda function.

Set the LAMBDA_DOCKER_FLAGS to enable the debugger using NODE_OPTIONS:

1
services:
2
  localstack:
3
    ...
4
    environment:
5
      ...
6
      - LAMBDA_DOCKER_FLAGS=-e NODE_OPTIONS=--inspect-brk=0.0.0.0:9229 -p 9229:9229

Add a new task by creating/modifying the .vscode/tasks.json file:

1
{
2
    "version": "2.0.0",
3
    "tasks": [
4
        {
5
          "label": "Wait Remote Debugger Server",
6
          "type": "shell",
7
          "command": "while [[ -z $(docker ps | grep :9229) ]]; do sleep 1; done; sleep 1;"
8
        }
9
    ]
10
}

Create a new launch.json file or edit an existing one from the Run and Debug tab, then add the following configuration:

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "address": "127.0.0.1",
6
            "localRoot": "${workspaceFolder}",
7
            "name": "Attach to Remote Node.js",
8
            "port": 9229,
9
            "remoteRoot": "/var/task/",
10
            "request": "attach",
11
            "type": "node",
12
            "preLaunchTask": "Wait Remote Debugger Server"
13
        },
14
    ]
15
}

A simple example of a Node.js lambda, myindex.js could look like this:

1
exports.handler = async (event) => {
2
    console.log(event);
3
    const response = {
4
        statusCode: 200,
5
        body: "ok",
6
    };
7
    return response;
8
};

Create the lambda function using:

lstk aws lambda create-function --function-name func1 \
    --code S3Bucket="hot-reload",S3Key="$(pwd)/" \
    --handler myindex.handler \
    --runtime nodejs14.x \
    --timeout 150 \
    --role arn:aws:iam::000000000000:role/lambda-role

Now to debug your lambda function, click on the Debug icon with Attach to Remote Node.js configuration selected, and then invoke your lambda function:

lstk aws lambda invoke --function-name func1 \
    --cli-binary-format raw-in-base64-out \
    --payload '{"hello":"world"}' \
    output.txt

• Debug your Python Lambda Function
• Debug your JavaScript Lambda Function
• Debug your TypeScript Lambda Function
• Debug your Java Lambda Function