# AWS Lambda Functions
The AWS Toolkit for Visual Studio Code provides comprehensive support for AWS Lambda functions, enabling you to build, test, and deploy directly from VS Code.
Lambda is a fully managed, event-driven compute service that automatically runs your code in response to events from over 200 AWS services and software-as-a-service (SaaS) applications. For detailed information about the AWS Lambda service, see the [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) Developer Guide.
The following topics decribe how to work with AWS Lambda in the AWS Toolkit for Visual Studio Code.
**Topics**
+ [Working with AWS Lambda Functions](remote-lambda.md)
+ [AWS Lambda console to IDE](lambda-console-ide.md)
+ [AWS Lambda with LocalStack support](lambda-localstack.md)
+ [AWS Lambda remote debugging](lambda-remote-debug.md)
# Working with AWS Lambda Functions
The AWS Toolkit for Visual Studio Code allows you to work with your AWS Lambda functions in your local VS Code environment. With the AWS Toolkit, you can create, edit, test, debug, and deploy your Lambda functions, without having to leave the IDE. For detailed information about the AWS Lambda service, see the [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html) Developer Guide.
The following sections describe how to get started working with Lambda functions in the AWS Toolkit for Visual Studio Code.
**Note**
If you have already created Lambda functions by using the AWS Management Console, then you can invoke them from the Toolkit. Additionally, you can open your Lambda functions into VS Code from the AWS Lambda console, for additional information, see the [AWS Lambda console to IDE](lambda-console-ide.md) topic in this user guide. To create a new Lambda function in VS Code, follow the steps outlined in the [Creating a new serverless application (local)](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/sam-get-started.html#serverless-apps-create) topic in this user guide.
## Prerequisites
The following conditions must be met to work with the AWS Lambda service in the AWS Toolkit.
+ The latest version of the AWS Toolkit for Visual Studio Code is installed and set up with your AWS credentials.
+ Your AWS Identity and Access Management (IAM) managed permissions and policies are configured to work with the AWS Lambda service. For detailed information on how to configure your permissions and create a compatible AWS managed policy, see the [AWS Identity and Access Management for AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/security-iam.html) topic in the *AWS Lambda Developer Guide*.
+ You have existing AWS Lambda functions or are familiar with how to create one. For instructions on how to create a Lambda function, see the [Create your first Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) topic in the *AWS Lambda Developer Guide*.
## Invoking a Lambda Function
To invoke a Lambda function from your AWS account into VS Code, complete the following steps.
1. From the AWS Toolkit for Visual Studio Code, expand the AWS explorer.
1. From the AWS explorer, expand **Lambda** to view your Lambda resources.
1. Open the context menu for (right-click) the Lambda function your want to invoke, then choose **Invoke in the cloud** or choose the **Invoke in the cloud** icon to open the **Remote invoke configuration** menu in VS Code.
1. From the **Remote invoke configuration** menu, specify your **Payload** settings and add any additional information that is required for the event.
**Note**
The first invoke process may start running as soon as you choose **Invoke in the cloud** in the AWS explorer. The output is displayed in the **OUTPUT** tab of the VS Code terminal.
1. Choose the **Remote Invoke** button to invoke your function, The output is displayed in the **OUTPUT** tab of the VS Code terminal.
## Deleting a Lambda function
To delete a Lambda function, complete the following procedure.
**Warning**
Do not use this procedure to delete Lambda functions that are associated with [CloudFormation](https://docs.aws.amazon.com/cloudformation/). These functions must be deleted through your CloudFormation stack.
1. From the AWS Toolkit for Visual Studio Code, expand the AWS explorer.
1. From the AWS explorer, expand **Lambda** to view your Lambda resources.
1. Right-click the Lambda function your want to delete, then choose **Delete**.
1. When prompted, confirm that you want to delete your function.
After the function is deleted, it's no longer listed in the AWS explorer.
## Downloading a Lambda function
You can download code from a remote Lambda function into your VS Code workspace for editing and debugging.
**Note**
To download your Lambda function, you must be working in a VS Code workspace with an accessible folder and the AWS Toolkit only supports this feature with Lambda functions using Node.js and Python runtimes.
1. From the AWS Toolkit for Visual Studio Code, expand the AWS explorer.
1. From the AWS explorer, expand **Lambda** to view your Lambda resources.
1. Right-click the Lambda function your want to download, then choose **Download**.
1. Your Lambda function opens in the VS Code editor and displays in the AWS explorer when the download is complete. The AWS Toolkit also creates a *launch configuration* in the VS Code run panel allowing you to run and debug the Lambda function locally with AWS Serverless Application Model. For more information about using AWS SAM, see [Running and debugging a serverless application from template (local)](sam-get-started.md#serverless-apps-debug).
## Deploying updates for new Lambda functions
You can deploy updates to new Lambda functions from an unspecified, temporary location on your local machine.
**Note**
When there are un-deployed changes to your lambda files, you're notified by the **M** icon located next to the modified files in the VS Code editor and in the AWS explorer.
**Deploying from the VS Code editor**
1. Open a file from your Lambda function in the VS Code editor, then make a change to the file.
1. Manually save from the VS Code main menu or pressing **option\$1s** (Mac) **ctrl\$1s** (Windows).
1. VS Code automatically prompts you about deploying your changes to the cloud, choose the **Deploy** button to confirm the deployment.
1. VS Code updates you on the status of your deployment and notifies you when the process is complete.
**Deploying from the AWS Explorer**
1. Open a file from your Lambda function in the VS Code editor, then make a change to the file.
1. From the AWS Toolkit, expand the AWS explorer.
1. From the AWS explorer, expand the AWS region with the Lambda function that you want to deploy changes for.
1. From the AWS region, expand Lambda and navigate the function that you want to deploy changes for.
1. From the quick menu next to your function, choose the **Save and deploy your code** icon.
1. VS Code updates you on the status of your deployment and notifies you when the process is complete.
## Uploading updates for existing Lambda functions
The following procedures describe how to upload local changes made to your existing Lambda functions. This feature supports uploads with any Lambda supported runtime.
**Warning**
Before uploading your lambda function, be aware of the following:
Updating code in this way doesn't use the AWS SAM CLI for deployment or create an CloudFormation stack
The AWS Toolkit doesn't validate code. Validate your code and test your function(s) before uploading any changes to the cloud.
**Uploading a Zip Archive**
1. From the AWS Toolkit for Visual Studio Code, expand the AWS explorer.
1. From the AWS explorer, expand **Lambda** to view your Lambda resources.
1. Right-click the Lambda function your want to upload your changes to, then choose **Upload Lambda...** to open the **Select Upload Type** menu.
1. Choose **ZIP Archive** to locate the `ZIP Archive` in your local directory.
1. When prompted, confirm the upload to start the upload of the selected `ZIP Archive`.
1. The status of your upload is displayed in VS Code and you're notified when the upload process is complete.
**Uploading a directory without building**
1. From the AWS Toolkit for Visual Studio Code, expand the AWS explorer.
1. From the AWS explorer, expand **Lambda** to view your Lambda resources.
1. Right-click the Lambda function your want to upload your changes to, then choose **Upload Lambda...** to open the **Select Upload Type** menu.
1. Choose **Directory** to proceed to the **Build directory** screen.
1. From the **Build directory** screen, choose **No** to choose a local directory for upload.
1. When prompted, confirm the upload to upload the selected directory.
1. The status of your upload is displayed in VS Code and you're notified when the upload process is complete.
**Uploading a directory with a build**
**Note**
Be aware of the following:
This procedure requires the AWS Serverless Application Model CLI.
The AWS Toolkit notifies you a matching handler can't be detected prior to upload.
To change the handler attached to your Lambda function, use the AWS Lambda console or the AWS Command Line Interface.
1. From the AWS Toolkit for Visual Studio Code, expand the AWS explorer.
1. From the AWS explorer, expand **Lambda** to view your Lambda resources.
1. Right-click the Lambda function your want to upload your changes to, then choose **Upload Lambda...** to open the **Select Upload Type** menu.
1. Choose **Directory** to proceed to the **Build directory** screen.
1. From the **Build directory** screen, choose **Yes**, then select a local directory for upload.
1. When prompted, confirm the upload to start building and uploading the selected directory.
1. The status of your upload is displayed in VS Code and you're notified when the upload process is complete.
## Converting your Lambda function to an AWS SAM project
To convert your Lambda function into an AWS SAM stack, complete the following steps.
**Warning**
Currently, only a subset of resources are supported when converting a Lambda function to an AWS SAM project. To locate any missing resources after a conversion, check the Lambda console and add them manually to your AWS SAM template. For additional details about supported and unsupported resources, see the [Resource type support](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html) topic in the *AWS CloudFormation Developer Guide*.
1. From the AWS Toolkit, expand the AWS explorer.
1. From the AWS explorer, expand the AWS region with the Lambda function that you want to convert into an AWS SAM project.
1. From the AWS region, expand Lambda and navigate the function that you want to convert into an AWS SAM stack.
1. From the quick menu next to your Lambda function, choose the **Convert to SAM Application** icon to browse your local file system and specify a location for your new AWS SAM project.
1. After specifying a location the AWS Toolkit begins converting your Lambda function into an AWS SAM project, VS Code provides updates on the status of the process.
**Note**
This process may take a few minutes.
1. When prompted by VS Code, enter a stack name, then press the **Enter** key to continue.
1. VS Code continues to update you with the status of your project, then notifies your when the process is complete and opens your new AWS SAM project as a VS Code workspace.
# AWS Lambda console to IDE
The AWS Lambda console to IDE feature allows you to download your AWS Lambda functions from the AWS Lambda console into VS Code. Working with your Lambda functions in VS Code gives you access to other local-development options such as AWS Serverless Application Model (AWS SAM) and the AWS Cloud Development Kit (AWS CDK).
For more information about AWS Lambda, see the [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html) Developer Guide. To get started working with your Lambda function in the AWS Toolkit, see the [Working with AWS Lambda Functions](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/remote-lambda.html) topic in this user guide. The following sections describe how to move your work flow from the Lambda console to VS Code. For detailed information about moving your Lambda functions from the Lambda console to VS Code, including how to get started working with the Lambda console, see the [Developing Lambda functions locally with VS Code](https://docs.aws.amazon.com/lambda/latest/dg/foundation-iac-local-development.html) topic in the *AWS Lambda Developer Guide*.
## Moving from console to local development
To open a Lambda function from the Lambda console in VS Code, complete the following steps:
1. From your web browser, open the [Lambda console](https://console.aws.amazon.com/lambda).
1. From Lambda console, choose the function you want to open in VS Code.
1. From the function view, navigate to the **Code source** tab.
1. From the **Code source** tab, choose **Open in VS Code**.
## Working with your Lambda function in VS Code
When your Lambda function opens in VS Code via the Lambda console:
+ VS Code automatically launches on your local machine.
+ Your Lambda function opens as a VS Code workspace.
+ Your Lambda `handler file` opens in the VS Code editor.
**Note**
If there is not a properly configured `handler file` in the workspace, no file opens in the VS Code editor.
Opening your Lambda function in VS Code via the Lambda console allows you to access all of the existing AWS Toolkit Lambda features, including the ability to edit function code with full language support, local testing, remote debugging, deployment support, and dependency management. For more information about Lambda features supported in the AWS Toolkit, see the [AWS Lambda](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/building-lambda.html) service table of contents in this user guide.
# AWS Lambda with LocalStack support
Build, test, and debug your serverless applications with LocalStack support in the AWS Toolkit for Visual Studio Code. LocalStack is an AWS Cloud emulator that allows for local testing of serverless applications.
For additional information about AWS Lambda, see the [AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/welcome.html) *Developer Guide*. To learn more about LocalStack, visit their website [LocalStack](https://www.localstack.cloud/).
## Prerequisites
The following are prerequisites to working with LocalStack in VS Code.
**Note**
The LocalStack CLI is installed during the setup process, but if you prefer a different version of the LocalStack CLI, the minium required version is *4.8.0*.
+ A LocalStack Web Application account is required for access to all features available for the free and paid LocalStack tiers. LocalStack community edition is available without an account.
+ Docker is required to work with LocalStack in VS Code. For more information about LocalStack requirements for Docker, see the LocalStack [Docker Images](https://docs.localstack.cloud/aws/capabilities/config/docker-images/) topic in the LocalStack documentation.
+ **Recommended:** The AWS Command Line Interface (AWS CLI) assists you in working with services in your simulated cloud environment.
## Installing LocalStack
To install LocalStack free and paid tiered versions, complete the following steps.
**Note**
For instructions on how to set up LocalStack Community edition, see the *LocalStack Community* content in the *Setting up LocalStack* section of this topic.
1. From the AWS Toolkit, expand the **APPLICATION BUILDER** explorer.
1. Choose the **Open Walkthrough** button to open the **Get started building your application** walkthrough tab in the VS Code editor.
1. From the walkthrough, choose the **Install LocalStack** to start the LocalStack installation process in VS Code.
## Setting up LocalStack
After you install the LocalStack extension for VS Code, you may see one of the following indicators when setup is needed:
+ In the VS Code Status Bar, located in the lower-left corner of the IDE by default, the LocalStack status is red.
+ VS Code prompts you to set up LocalStack.
There are two types of setup and configurations for LocalStack, depending on which version of LocalStack you're using. The following tabbed sections describe each LocalStack setup process.
**Note**
LocalStack auth tokens are required for the free and paid tier versions of LocalStack. For specific information about LocalStack pricing, see their [Choose your plan](https://www.localstack.cloud/pricing) pricing guide.
### LocalStack free and paid tiers
There are 2 ways to set up LocalStack.
+ From the VS Code **Setup LocalStack to get started** prompt, choose the **Setup** button.
+ From the VS Code status bar, choose the LocalStack status icon to open the **Setup LocalStack to get started** prompt, then choose the **Setup** button.
During setup, the system goes through the following steps:
1. Installs the LocalStack CLI.
1. Checks to see if you have a LocalStack account.
1. If you have a LocalStack account, the system guides you through the authentication process in your default web browser. Similarly, if you do not have a LocalStack account, the system guides you through account setup before the authentication process.
After LocalStack is set up, the LocalStack status updates in the VS Code status bar.
**Note**
If you haven't created an AWS profile for LocalStack, then a new one is automatically created for you as part of the LocalStack setup process.
### LocalStack Community
The Community edition of LocalStack is free to use and doesn't require you to sign up for an account, it runs from a Docker image that doesn't require a license. For additional details about LocalStack Community Edition, see the [LocalStack Community image](https://docs.localstack.cloud/references/docker-images/) documentation. The following sections describe prerequisites and the basic setup that is required to work with LocalStack community edition in VS Code.
**Launching a new instance**
To launch a new instance of LocalStack Community, complete the following procedure.
**Note**
The following example starts a container instance of LocalStack on port 4566. If you specify different port values, you must update the port value specified in the procedure located in the *Configuring the AWS CLI and AWS Toolkit* section.
1. From VS Code, open the VS Code terminal by pressing **ctrl \$1 `(backtick)**.
1. Enter the following into the terminal.
**Mac:**
```
docker run -d --name localstack_main \
>> -p 4566:4566 \
>> -v /var/run/docker.sock:/var/run/docker.sock \
>> localstack/localstack
```
**Windows:**
```
docker run -d --name localstack_main `
>> -p 4566:4566 `
>> -v /var/run/docker.sock:/var/run/docker.sock `
>> localstack/localstack
```
1. The terminal updates with the status of your Docker instance when the process is complete.
This containerized instance of LocalStack gives you access to the AWS services that you specified during the download process.
**Configuring the CLI for LocalStack and Docker.**
To configure the AWS CLI and AWS Toolkit to work with LocalStack in Docker, set up a new profile by completing the following steps:
1. From VS Code, open the VS Code terminal by pressing **ctrl \$1 `(backtick)**.
1. Enter the following into the terminal.
```
~/.aws/credentials
[localstack]
aws_access_key_id = test
aws_secret_access_key = test
~/.aws/config
[profile localstack]
region = us-east-1
output = json
endpoint_url = http://localhost:4566 [default localstack endpoint]
```
1. The AWS Toolkit detects your LocalStack profile and updates the connection status menu.
After setup, choosing your LocalStack profile from the AWS profile section of the status bar makes your LocalStack resources visible in the AWS explorer. Additionally, you can view your LocalStack logs in the **Output** tab of the VS Code terminal.
## Starting LocalStack in VS Code
You can start LocalStack using any of the following methods:
**Starting LocalStack from the VS Code Status Bar**
1. From VS Code, navigate to the status bar, then choose the **Start LocalStack** button to launch LocalStack.
1. The VS Code Status Bar updates when LocalStack has launched successfully.
**Starting LocalStack from the VS Code **Command Palette****
1. From VS Code, open the **Command Palette** by pressing **Cmd \$1 Shift \$1 P** (Mac) or **Control \$1 Shift \$1 P** (Windows).
1. From the **Command Palette**, enter **Start LocalStack** in the search bar and choose it from the list when it populates in the results.
1. The VS Code Status Bar updates when LocalStack has launched successfully.
**Starting LocalStack from the VS Code terminal**
1. From VS Code, open the VS Code terminal by pressing **ctrl \$1 `(backtick)**.
1. From the VS Code terminal, enter **localstack start** CLI command.
1. The VS Code Status Bar updates when LocalStack has launched successfully.
## Building a sample serverless application
To start working with LocalStack in VS Code, you need a sample serverless application. If you already have an existing application in your AWS account you can deploy it locally using LocalStack or you can create a new application with AWS Serverless Land.
For additional information about creating an application with Serverless Land in the AWS Toolkit, see the [Working with AWS Serverless Land](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/serverlessland-overview.html) topic in this User Guide. For detailed information about Serverless Land, see the [Serverless Land](https://serverlessland.com/) web-application main landing page.
## Testing and debugging Lambda functions with LocalStack
Testing and debugging your Lambda functions in the LocalStack VS Code extension is similar to working with your functions deployed to the AWS cloud. The main difference is that your AWS Toolkit instance must be authenticated with your LocalStack account to deploy and debug your functions with LocalStack.
**Note**
The testing and debugging features described in this section are not available for LocalStack Community edition.
To work with LocalStack in VS Code, connect to your LocalStack profile in the AWS Toolkit. When your LocalStack profile is active, the VS Code status bar shows **AWS: profile:localstack (custom endpoint)** with a check mark.
For detailed information about working with your Lambda functions in the AWS Toolkit, see the [Working with AWS Lambda functions](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/remote-lambda.html) topic in this user guide.
# AWS Lambda remote debugging
The AWS Toolkit for Visual Studio Code enables you to debug your AWS Lambda functions that are running in the cloud, directly in VS Code. With AWS Lambda remote debugging you can inspect running functions, set breakpoints, examine variables, and step-through debugging without modifying their existing development workflow.
The following sections describe how to work with Lambda remote debugging in the AWS Toolkit for Visual Studio Code.
## How Lambda remote debugging works
The AWS Toolkit enables remote debugging by temporarily modifying your Lambda functions with an additional Lambda debugging layer and extending the Lambda invoke timeout limit to 900 seconds. A secure connection is established between your local debugger and the Lambda runtime environment using AWS IoT Secure Tunneling. This connection allows you to use your local-code breakpoints to step through the function as it executes remotely. After your debugging session is complete, all of the temporary modifications are automatically reverted to their original settings.
## Getting Started
### Supported runtimes
The following runtimes are supported by Lambda remote debugging.
+ Python (Amazon Linux 2023)
+ Java
+ Typescript/JavaScript/Node.js (Amazon Linux 2023)
**Note**
Lambda managed instances and OCI image function types are not supported by Lambda remote debugging.
### Prerequisites
Before you begin, the following prerequisites must be met.
+ You must have valid AWS credentials configured in the AWS Toolkit. For additional details about installing the AWS Toolkit and configuring your credentials, see the [Getting started](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/setting-up.html) topic in this user guide.
+ A Lambda function has been deployed to your AWS account. For details on deploying a Lambda function, see the [Create your first Lambda function](https://docs.aws.amazon.com//lambda/latest/dg/getting-started.html) topic in the *AWS Lambda* Developer Guide.
+ You must have appropriate AWS Identity and Access Management (IAM) policy and permissions to debug your function. For additional details on Lambda permissions, see the [AWS managed policies for AWS Lambda](https://docs.aws.amazon.com//lambda/latest/dg/security-iam-awsmanpol.html) topic in the *AWS Lambda* Developer Guide. The following is an example of a policy that contains the minimum required permissions for working with Lambda remote debugging in the AWS Toolkit.
**Note**
Remote debugging is enabled through AWS AWS IoT Secure Tunneling. This allows your local debugger to establish a secure connection to the Lambda runtime environment.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"lambda:ListFunctions",
"lambda:GetFunction",
"lambda:GetFunctionConfiguration",
"lambda:GetLayerVersion",
"lambda:UpdateFunctionConfiguration",
"lambda:InvokeFunction",
"lambda:PublishVersion",
"lambda:DeleteFunction",
"iot:OpenTunnel",
"iot:RotateTunnelAccessToken",
"iot:ListTunnels"
],
"Resource": "*"
}
]
}
```
## Accessing Lambda remote debugging
There are two main paths to access Lambda remote debugging in the AWS Toolkit: the AWS explorer or the Application Builder explorer. From the AWS explorer, you can access Lambda remote debugging through your AWS Lambda nodes. From the Application Builder explorer, you can access Lambda remote debugging through your local AWS SAM projects.
**Accessing Lambda remote debugging from the AWS explorer**
1. From VS Code, open the AWS Toolkit extension.
1. From the AWS Toolkit, expand the AWS explorer.
1. From the explorer, expand the **Lambda** node.
1. Navigate to the function you want to debug, then choose the **Invoke remotely** icon from the context menu to open the **Remote invoke configuration** screen.
**Accessing Lambda remote debugging from the Application Builder explorer.**
1. From VS Code, open the AWS Toolkit extension.
1. From the AWS Toolkit, expand the application builder explorer.
1. From the explorer expand the `AWS SAM` project that contains the Lambda project you want to debug.
1. Expand the deployed `Lambda` function that you want to debug.
1. Navigate to the function remote, then choose the **Invoke remotely** icon from the context menu to open the **Remote invoke configuration** screen.
## Working with Lambda remote debugging
The following sections describe how to work with Lambda remote debugging in the AWS Toolkit for Visual Studio Code.
**Note**
Lambda functions have a 5-layer limit and a 250MB combined limit for function code and all attached layers. Lambda remote debugging requires at least 1 free layer to run.
### Setting up a debugging session
Before you begin, configure your debugging session by completing the following procedure.
1. Open the **Remote invoke configuration** menu by completing the *Accessing Lambda remote debugging from the AWS explorer* or the *Accessing Lambda remote debugging from the Application Builder explorer* procedure, located in the previous section.
1. From the **Remote invoke configuration** menu, select the **Remote Debugging** check box to display the remote debugging properties.
1. Specify the **Local Root Path** to your local handler file.
**Note**
The local root path is the location of your source code that matches the deployed Lambda function. If you're working from a deployed function in the Application Builder explorer, your local root path is automatically detected.
If you don't have the source code stored locally, choose the **Download remote code** button to retrieve your Lambda function source code. This will open your `handler file` in the VS Code editor.
1. From the **Payload** section, specify where your test-event data is obtained.
### Setting breakpoints and debugging
Set breakpoints and begin debugging by completing the following procedure.
1. From your `handler file` in the VS Code editor, click in the gutter-margin to set breakpoints at the line numbers where you want to pause debugging.
1. When you're satisfied with the breakpoints, return to the **Remote invoke configuration** menu to verify that your settings are configured correctly, then choose the **Remote invoke** button to start debugging.
1. The AWS Toolkit updates your Lambda function with debugging capabilities, establishes a secure tunnel for the debugging session, invokes your function with the specified payload, then pauses the process when it reaches a breakpoint.
1. At a breakpoint pause, use the **RUN AND DEBUG** pane to view your **VARIABLES**, **CALL STACK**, and **BREAKPOINTS**.
### Updating and testing your function
To modify your code and test changes with a quick deployment, complete the following procedure.
1. With your debugging session active, make changes to your `handler file` in the VS Code editor.
1. Save your changes (**Command\$1S on macOS**,**Ctrl\$1S on Windows**)
1. When prompted, confirm that you wish to proceed to deploy your changes. The AWS Toolkit will update your Lambda function with the modified code.
1. Continue debugging and testing your changes by setting new breakpoints and selecting the **Remote invoke** button again.
**Note**
Alternatively, you can deselect the **Attach debugger** option in the VS Code debugging controls and choose the **Remote invoke** button to run your function without debugging.
### Ending a debugging session
Each of the following options ends your remote debugging session and removes the debug layer from your project.
+ Choosing the **Remove Debug Setup** option from the **Remote invoke configuration** screen.
+ Choosing the **disconnect** icon from the VS Code debugging controls.
+ Closing the `handler file` in the VS Code editor.
**Note**
Take note of the following:
The Lambda debug layer is automatically removed after 60 seconds of inactivity. The count begins when your last invoke is complete.
If you made code changes to your infrastructure-as-code (IaC) managed (AWS SAM, AWS CDK, Terraform) functions during the debugging process, save them to your local project and consider updating your source-control repository. Unsaved changes are overwritten when your IaC function redeploys.
If you made temporary changes for debugging purposes only, you may want to redeploy your function from your source control to ensure it matches your production code.
### Debugging TypeScript Lambda functions with source maps
The following sections describe how to debug your TypeScript Lambda functions with source maps.
#### Prerequisites
To debug your TypeScript Lambda functions, the following prerequisites must be met.
+ Your TypeScript must be compiled with the source map option enabled. For additional information, see the [JavaScript source map support](https://code.visualstudio.com/docs/typescript/typescript-debugging#_javascript-source-map-support) topic in the VS Code documentation.
+ In-line source maps are not supported. You must use a separate `.js.map` file to store the source map.
#### Configuration
To configure Lambda remote debugging for TypeScript Lambda functions in the AWS Toolkit, complete the following steps.
1. From the AWS Toolkit, expand the AWS explorer.
1. From the explorer, expand the **Lambda** node.
1. Navigate to the function you want to configure for TypeScript, then choose the **Invoke remotely** icon from the context menu to open the **Remote invoke configuration** screen.
1. Enable remote debugging by select the **Remote debugging** check box.
1. Configure your **Local Root Path** by pointing to the directory containing your `TypeScript handler file`.
**Note**
The `TypeScript handler file` is where you set your debugging breakpoints.
1. Expand **Remote debug additional configuration** settings.
1. Enable source mapping by selecting the **Source map** check box.
1. Set the **Out files** field to the local directory of your Lambda function copy.
**Example**
If `app.js` and `app.map` are in `.aws-sam/build/HelloWorldFunction`, then make the **Out files** location `/Users/user/project/aws-sam/build/HelloWorldFunction/*`.
**Note**
The **Out file** path should be an absolute path.
For AWS SAM and AWS CDK projects, the AWS Toolkit supports automatic source map detection. If the **Out files** field is left empty for these projects, the toolkit will automatically attempt to detect the source map location.
1. When you're satisfied with the settings, choose the **Remote invoke** button to begin debugging your TypeScript function.
## Troubleshooting and advanced use cases
If your debug session fails, start the troubleshooting process by completing these steps.
1. Update the AWS Toolkit to the latest version.
1. Refresh the web view by closing the **Remote invoke configuration** web view and reopening it.
1. Restart VS Code by closing it completely and reopening it.
1. Open the VS Code Command Palette and enter the command **AWS: Reset Lambda Remote Debugging Snapshot**, select it when it populates in the results to reset your Lambda remote debugging snapshot.
1. If you're not able to troubleshoot the problem, submit an issue to [AWS Toolkit for Visual Studio Code GitHub Issues](https://github.com/aws/aws-toolkit-vscode/issues).
### Advanced use case: code-signing configuration
Remote debugging requires attaching a debug layer to your Lambda function. If your function has code-signing configuration enabled and enforced, the AWS Toolkit can't automatically attach the debug layer to your function.
There are two options to resolve the code-signing configuration issue.
+ Temporarily remove code signing.
+ Use a signed debug layer.
#### Temporarily removing code signing
Update the code-signing configuration by setting `UntrustedArtifactOnDeployment : Warn`, then re-enable it back to `Enforced` after the debugging process is complete.
For more information, see the [UpdateCodeSigningConfig](https://docs.aws.amazon.com//lambda/latest/api/API_UpdateCodeSigningConfig.html) reference in the *AWS Lambda API Reference*.
#### Using a signed debug layer
1. From Lambda remote debugging in the AWS Toolkit, expand the **Remote debug additional configuration** section.
1. From the **Remote debug additional configuration** section, copy your Region layer ARN from the **Layer override** field.
1. From the AWS CLI, use the following command to download the layer version `aws lambda get-layer-version-by-arn --arn layer-arn`, replacing *layer-arn* with your layer ARN. For detailed instructions on how to download the signed debug layer, see the [get-layer-version-by-arn](https://docs.aws.amazon.com/cli/latest/reference/lambda/get-layer-version-by-arn.html) reference in the *AWS CLI Command Reference*.
1. Sign the layer with your code-signing configuration and publish it to your account. For signing and publishing guidance, see the [Set up code signing for your AWS SAM application](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/authoring-codesigning.html) topic in the *AWS Serverless Application Model Developer Guide*.
1. After the layer has been signed and published to your account, return to the **Remote debug additional configuration** section of Lambda remote debugging, then enter the new layer ARN into the **Layer override** field. When the process is complete, Lambda remote debugging uses your signed layer instead of the default layer.
### Advanced use case: debugging functions with SnapStart or provisioned concurrency
For Lambda functions configured with SnapStart or provisioned concurrency, publishing a new version takes significantly more time. To speed up your debugging workflow, you can configure Lambda remote debugging to update only the `$LATEST` version of your function instead of publishing a new version.
1. From the **Remote invoke configuration** screen, expand the **Remote debug additional configuration** settings.
1. Deselect the **Publish version** option.
1. The AWS Toolkit will now only update your function's `$LATEST` version and debug using it.
**Note**
As a side effect of debugging with the `$LATEST` version, you should avoid other traffic that may invoke your `$LATEST` version to ensure an undisturbed debugging environment.
### Supported regions
The following error occurs when a region doesn't support remote debugging.
```
Region ${region} doesn't support remote debugging yet
```
The following is a list of supported regions.
+ ap-east-1
+ ap-northeast-1
+ ap-northeast-2
+ ap-south-1
+ ap-southeast-1
+ ap-southeast-2
+ ca-central-1
+ eu-central-1
+ eu-north-1
+ eu-west-1
+ eu-west-2
+ eu-west-3
+ me-central-1
+ me-south-1
+ sa-east-1
+ us-east-1
+ us-east-2
+ us-west-1
+ us-west-2
### Lambda RequestEntityTooLargeException
Lambda functions have a 5-layer limit and a 250MB combined limit for function code and all attached layers. The remote debugging layer is approximately 40MB, which may cause your function to exceed this limit if you have a large function package or multiple layers. For additional details, see the [Lambda: InvalidParameterValueException or RequestEntityTooLargeException](https://docs.aws.amazon.com//lambda/latest/dg/troubleshooting-deployment.html#troubleshooting-deployment-InvalidParameterValueException1) topic section in the *AWS Lambda Developer Guide*.
The following list describes ways to troubleshoot and correct this error.
+ **Reduce function size**: Optimize your function code and remove unnecessary dependencies.
+ **Remove unused layers**: Temporarily remove non-essential layers during debugging.
+ **Use external dependencies**: Move large dependencies to external storage, such as Amazon S3, and load them at runtime.
### Troubleshooting Java debugging
To debug a Java Lambda function, you must have the same Java version installed locally that matches your Lambda function's runtime version.
For example, when debugging a Java 25 function, you must have Java 25 installed in your local environment where the AWS Toolkit is running. If you attempt to debug a Java 25 function with Java 21 or an earlier version installed locally, remote debugging will not be able to stop at the breakpoints you set.
Ensure your local Java version matches your Lambda function's runtime version before starting a debugging session.
### IoT secure tunneling quota exceeded
The following is an example of the *tunnel quota exceeded error* that occurs when you've reached the daily limit for AWS IoT secure tunneling connections in Lambda remote debugging.
```
Error creating/reusing tunnel: LimitExceededException: Exceeded quota of Lambda debugging tunnels
```
AWS IoT Secure Tunneling connection have the following quotas:
+ Free-tier IoT secure tunneling is allotted 10 connections per day.
+ Each tunnel supports one VS Code instance for up to 12 hours.
+ The quota applies per AWS account, per day.
If you encounter the AWS IoT secure tunneling error, wait for the daily quota reset or contact AWS support to request a quota-limit increase. For AWS support contact info, see the [AWS support contact portal](https://aws.amazon.com/contact-us/). For detailed information about AWS IoT secure tunneling, see the [AWS IoT secure tunneling](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html) topic in the *AWS IoT Developer Guide*.