# Working with serverless applications The AWS Toolkit for Visual Studio Code provides support for [AWS Serverless Application](https://aws.amazon.com/serverless/). The following topics describe how to get started creating and working with AWS Serverless Application Model (AWS SAM) applications, from the AWS Toolkit for Visual Studio Code. **Topics** + [Getting Started with serverless applications](sam-get-started.md) + [Working with AWS Serverless Land](serverlessland-overview.md) + [Running and debugging Lambda functions directly from code](serverless-apps-run-debug-no-template.md) + [Running and debugging local Amazon API Gateway resources](debug-apigateway.md) + [Configuration options for debugging serverless applications](serverless-apps-run-debug-config-ref.md) + [Troubleshooting serverless applications](serverless-apps-troubleshooting.md) # Getting Started with serverless applications The following sections describe how to get started creating an AWS Serverless Application from the AWS Toolkit for Visual Studio Code, using AWS Serverless Application Model (AWS SAM) and CloudFormation stacks. ## Prerequisites Before you can create or work with an AWS Serverless Application, the following prerequisites must be completed. **Note** The following operations may require you to exit or restart VS Code before the changes are complete. + Install the AWS SAM command line interface (CLI). For additional information and instructions on how to install the AWS SAM CLI, see the [Installing the AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) topic in this *AWS Serverless Application Model User Guide*. + From your AWS config file, identify your default AWS Region. For more information on your config file, see the [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) topic in the *AWS Command Line Interface User Guide*. + Install your language SDK and configure your toolchain. For additional information on how to configure your toolchain from the AWS Toolkit for Visual Studio Code see the [configure your toolchain](setup-toolchain.md) topic in this User Guide. + Install the [YAML language support extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) from the VS Code marketplace. This is required for the CodeLens feature of AWS SAM template files are accessible. For additional information about CodeLens, see the [CodeLens](https://code.visualstudio.com/api/language-extensions/programmatic-language-features#codelens-show-actionable-context-information-within-source-code) section in the VS Code documentation ## IAM permissions for serverless applications In the Toolkit for VS Code you must have a credentials profile that contains the AWS Identity and Access Management (IAM) permissions necessary to deploy and run serverless applications. You must have appropriate read/write access to the following services: CloudFormation, IAM, Lambda, Amazon API Gateway, Amazon Simple Storage Service (Amazon S3), and Amazon Elastic Container Registry (Amazon ECR). For additional information about setting up authentication required to deploy and run serverless applications, see the [Managing resource access and permissions](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-permissions.html) in the *AWS Serverless Application Model Developer Guide*. For information on how to set up your credentials, see the [AWS IAM credentials](setup-credentials.md) in this User Guide. ## Creating a new serverless application (local) This procedure shows how to create a serverless application with the Toolkit for VS Code by using AWS SAM. The output of this procedure is a local directory on your development host containing a sample serverless application, which you can build, locally test, modify, and deploy to the AWS Cloud. 1. To open the **Command Palette**, choose **View**, **Command Palette**, and then enter **AWS**. 1. Choose **AWS Toolkit Create Lambda SAM Application**. ![\[Command palette dialog box.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/sam-create-app-cmdlet-updated.png) **Note** If the AWS SAM CLI isn't installed, you get an error in the lower-right corner of the VS Code editor. If this happens, verify that you've met all the [assumptions and prerequisites](#serverless-apps-assumptions). 1. Choose the runtime for your AWS SAM application. **Note** If you select one of the runtimes with "(Image)", your application is package type `Image`. If you select one of the runtimes without "(Image)", your application is type `Zip`. For more information about the difference between `Image` and `Zip` package types, see [Lambda deployment packages](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-package.html) in the *AWS Lambda Developer Guide*. 1. Depending on the runtime you select, you may be asked to select a dependency manager and a runtime architecture for your SAM application. ------ #### [ Dependency Manager ] Choose between **Gradle** or **Maven**. **Note** This choice of build automation tools is available only for Java runtimes. ------ #### [ Architecture ] Choose between **x86\$164** or **arm64**. The option to run your serverless application in an ARM64-based emulated environment instead of the default x86\$164-based environment is available for the following runtimes: + nodejs12.x (ZIP and image) + nodejs14.x (ZIP and image) + python3.8 (ZIP and image) + python3.9 (ZIP and image) + python3.10 (ZIP and image) + python3.11 (ZIP and image) + python3.12 (ZIP and image) + java8.al2 with Gradle (ZIP and image) + java8.al2 with Maven (ZIP only) + java11 with Gradle (ZIP and image) + java11 with Maven (ZIP only) **Important** You must install AWS CLI version 1.33.0 or later to allow applications to run in ARM64-based environments. For more information, see [Prerequisites](setup-toolkit.md#setup-prereq). ------ 1. Choose a location for your new project. You can use an existing workspace folder if one is open, **Select a different folder** that already exists, or create a new folder and select it. For this example, choose **There are no workspace folders open** to create a folder named `MY-SAM-APP`. 1. Enter a name for your new project. For this example, use `my-sam-app-nodejs`. After you press **Enter**, the Toolkit for VS Code takes a few moments to create the project. When the project is created, your application is added to your current workspace. You should see it listed in the **Explorer** window. ## Opening a serverless application (local) To open a serverless application on your local development host, open the folder that contains the application's template file. 1. From the **File**, choose **Open Folder...**. 1. In the **Open Folder** dialog box, navigate to the serverless application folder that you want to open. 1. Choose the **Select Folder** button. When you open an application's folder, it is added to the **Explorer** window. ## Running and debugging a serverless application from template (local) You can use the Toolkit for VS Code to configure how to debug serverless applications and run them locally in your development environment. You start to configure debug behavior by using the VS Code [CodeLens](https://code.visualstudio.com/api/language-extensions/programmatic-language-features#codelens-show-actionable-context-information-within-source-code) feature to identify an eligible Lambda function. CodeLens enables content-aware interactions with your source code. For information about ensuring that you can access the CodeLens feature, review the [Prerequisites](#serverless-apps-assumptions) section from earlier in this topic. **Note** In this example, you debug an application that uses JavaScript. However, you can use Toolkit for VS Code debugging features with the following languages and runtimes: C\$1 – .NET Core 2.1, 3.1; .NET 5.0 JavaScript/TypeScript – Node.js 12.*x*, 14.*x* Python – 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 Java – 8, 8.al2, 11 Go – 1.x Your language choice also affects how CodeLens detects eligible Lambda handlers. For more information, see [Running and debugging Lambda functions directly from code](serverless-apps-run-debug-no-template.md). In this procedure, you use the example application created in the [Creating a new serverless application (local)](#serverless-apps-create) section earlier in this topic. 1. To view your application files in VS Code's File Explorer, choose **View**, **Explorer**. 1. From the application folder (for example, *my-sample-app*), open the `template.yaml` file. **Note** If you use a template with a name that's different from `template.yaml`, the CodeLens indicator isn't automatically available in the YAML file. This means that you must manually add a debug configuration. 1. In the editor for `template.yaml`, go to the `Resources` section of the template that defines serverless resources. In this case, this is the `HelloWorldFunction` resource of type `AWS::Serverless::Function`. In the CodeLens indicator for this resource, choose **Add Debug Configuration**. ![\[Using the CodeLens indicator in the template.yaml file to add a debug configuration.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/yaml_template_debug.png) 1. In the **Command Palette**, select the runtime in which your AWS SAM application will run. 1. In the editor for the `launch.json` file, edit or confirm values for the following configuration properties: + `"name"` – Enter a reader-friendly name to appear in the **Configuration** drop-down field in the **Run** view. + `"target"` – Ensure that the value is `"template"` so that the AWS SAM template is the entry point for the debug session. + `"templatePath"` – Enter a relative or absolute path for the `template.yaml` file. + `"logicalId"` – Ensure that the name matches the one specified in the **Resources** section of the AWS SAM template. In this case, it's the `HelloWorldFunction` of type `AWS::Serverless::Function`. ![\[Configuring the launch.json file for template-based debugging.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/template_based_config_updated.png) For more information about these and other entries in the `launch.json` file, see [Configuration options for debugging serverless applications](serverless-apps-run-debug-config-ref.md). 1. If you're satisfied with your debug configuration, save `launch.json`. Then, to start debugging, choose the green "play" button in the **RUN** view. When the debugging sessions starts, the **DEBUG CONSOLE** panel shows debugging output and displays any values returned by the Lambda function. (When debugging AWS SAM applications, the **AWS Toolkit** is selected as the **Output** channel in the **Output** panel.) ## Syncing AWS SAM applications The AWS Toolkit for Visual Studio Code runs the AWS SAM CLI command `sam sync` to deploy your serverless applications to the AWS Cloud. For additional information about AWS SAM sync, see the [AWS SAM CLI command reference](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html) topic in the *AWS Serverless Application Model Developer Guide* The following procedure describes how to deploy your serverless applications to the AWS Cloud with `sam sync` from the Toolkit for VS Code. 1. From the main menu in VS Code, open the **Command Palette** by expanding **View** and choosing **Command Palette**. 1. From the **Command Palette** search for **AWS** and choose **Sync SAM Application** to start setting up your sync. ![\[Command to sync a serverless application.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/samsync032023.png) 1. Choose the AWS Region to sync your serverless application to. 1. Choose the `template.yaml` file to use for the deployment. 1. Select an existing Amazon S3 bucket or enter a new Amazon S3 bucket name to deploy your application to. **Important** Your Amazon S3 bucket must meet the following requirements: The bucket must be in the Region that you're syncing to. The Amazon S3 bucket name must be globally unique across all existing bucket names in Amazon S3. 1. If your serverless application includes a function with package type `Image`, enter the name of an Amazon ECR repository that this deployment can use. The repository must be in the Region that you're deploying to. 1. Select a deployment stack from the list of your previous deployments, or create a new deployment stack be entering a new stack name. Then, proceed to begin the sync process. **Note** Stacks used in previous deployments are recalled per workspace and region. 1. During the syncing process, the status of your deployment is captured in the **Terminal** tab of VS Code. Verify that your sync was successful from the terminal tab, if an error occurs you receive a notification. ![\[An error pop-up while deploying a serverless application.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/sam-deploy-error.png) **Note** For additional details about your sync, the AWS Toolkit for Visual Studio Code logs are accessible from the **Command Palette**. To access the your AWS Toolkit for Visual Studio Code logs from the Command Palette, expand **View**, choose **Command Palette**, then search for **AWS: View AWS Toolkits Logs**, and select it when it populates in the list. When the deployment is complete, you see your application listed in the **AWS Explorer**. For more information about how to invoke the Lambda function created as part of the application, see the [Working with AWS Lambda Functions](remote-lambda.md) topic in this User Guide. ## Deleting a serverless application from the AWS Cloud Deleting a serverless application involves deleting the CloudFormation stack that you previously deployed to the AWS Cloud. Note that this procedure does not delete your application directory from your local host. 1. Open the [AWS Explorer](aws-explorer.md). 1. In the **AWS Toolkit Explorer** window, expand the Region containing the deployed application that you want to delete, and then expand **CloudFormation**. 1. Open the context (right-click) menu for the name of the CloudFormation stack that corresponds to the serverless application that you want to delete, and then choose **Delete CloudFormation Stack**. 1. To confirm that you want to delete the selected stack, choose **Yes**. If the stack deletion succeeds, the Toolkit for VS Code removes the stack name from the CloudFormation list in **AWS Explorer**. # Working with AWS Serverless Land AWS Serverless Land in the AWS Toolkit for Visual Studio Code is a collection of features that assists you with building event-driven architectures. The following topic sections describe how to work with Serverless Land in the AWS Toolkit. For detailed information about Serverless Land, see the [Serverless Land](https://serverlessland.com/) web application. ## Accessing Serverless Land There are 3 main entry points to access Serverless Land in the AWS Toolkit: + The VS Code Command Palette + The AWS Toolkit Explorer + The AWS Toolkit **Application Builder** explorer ### Opening Serverless Land from the VS Code Command Palette To open Serverless Land from the VS Code Command Palette, complete the following steps. 1. From VS Code, open the Command Palette by pressing **option\$1shift\$1p** (Mac) or **control\$1shift\$1p** (Windows). 1. From the VS Code Command Palette, enter **AWS Create application with Serverless template** into the search bar. 1. Choose **AWS: Create application with Serverless template** when it populates in the list. 1. The Serverless Land wizard opens to the **Select a Pattern for you application (1/5)** screen in VS Code when the process is complete. ### Opening Serverless Land from the AWS Toolkit Explorer. To open Serverless Land from the AWS Toolkit Explorer, complete the following steps. 1. From the AWS Toolkit Explorer, expand the region that you want to open Serverless Land in. 1. Open the context menu for (right-click) the Lambda node. 1. Choose **Create application with Serverless template** from the context menu. 1. The Serverless Land wizard opens to the **Select a Pattern for you application (1/5)** screen in VS Code when the process is complete. ### Opening Serverless Land from the Application Builder explorer To open Serverless Land from the AWS Toolkit Application Builder explorer, complete the following steps. 1. From the AWS Toolkit Explorer, navigate to the Application Builder explorer. 1. Right-click the Application Builder explorer and choose **Create application with Serverless template** from the context menu. 1. The Serverless Land wizard opens to the **Select a Pattern for you application (1/5)** screen in VS Code when the process is complete. ## Creating an application with Serverless template To create an application with Serverless template, complete the following steps. 1. From the Serverless Land wizard **Select a Pattern for you application (1/5)** screen, choose a Pattern for the base of your application. **Note** To view a preview and more details about a particular Pattern, choose the **Open in Serverless Land** icon located next to the Pattern you want to view. The Serverless Land Pattern opens in your default web browser. 1. From the **Select Runtime (2/5)** screen, choose a runtime for your project. 1. From the **Select IaC (3/5)** screen, choose an IaC option for your project. 1. From the **Select a project location (4/5)** screen, choose a location to store your project. 1. From the **Enter Project Name (5/5)** screen, enter a name for your new application. 1. Your new application displays in the VS Code explorer and your project `readme.md` opens in the VS Code editor, when the procedure is complete. **Note** After your new application is created, additional actions that are specific to your application type can be found in the `readme.md` file. Additionally, your AWS Serverless Application Model (AWS SAM) applications can be opened with AWS Application Builder for local testing, debugging, and more. For details about working with Application Builder in the AWS Toolkit, see the [Working with the AWS Application Builder explorer](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/appbuilder-overview-overview.html) topic in this User Guide. # Running and debugging Lambda functions directly from code When testing the AWS SAM application, you can choose to run and debug just the Lambda function and exclude other resources that the AWS SAM template defines. This approach involves using the [CodeLens](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup) feature to identify Lambda function handlers in the source code that you can directly invoke. The Lambda handlers that are detected by CodeLens depend on the language and runtime that you're using for your application. | Language/runtime | Criteria for Lambda functions to be identified by CodeLens indicators | | --- | --- | | C\$1 (dotnetcore2.1, 3.1; .NET 5.0) | The function has the following features:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-no-template.html) The [ms-dotnettools.csharp extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) (or any extension that provides language symbols for C\$1) is installed and enabled. | | JavaScript/TypeScript (Node.js 12.x, 14.x) | The function has the following features:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-no-template.html) | | Python (3.7, 3.8, 3.9, 3.10, 3.11, 3.12) | The function has the following features:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-no-template.html) The [ms-python.python extension](http://marketplace.visualstudio.com/items?itemName=ms-python.python) (or any extension that provides language symbols for Python) is installed and enabled. | | Java (8, 8.al2, 11) | The function has the following features:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-no-template.html) The [redhat.java extension](https://marketplace.visualstudio.com/items?itemName=redhat.java) (or any extension that provides language symbols for Java) is installed and enabled. This extension requires Java 11, no matter which Java runtime you're using. The [vscjava.vscode-java-debug](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) extension (or any extension that provides a Java debugger) is installed and enabled. | | Go (1.x) | The function has the following features:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-no-template.html) The [golang.go extension](https://marketplace.visualstudio.com/items?itemName=golang.Go) is installed, configured, and enabled. | # To run and debug a serverless application directly from the application code 1. To view your application files in the VS Code File Explorer, choose **View**, **Explorer**. 1. From the application folder (for example, *my-sample-app*), expand the function folder (in this case, *hello-world*) and open the `app.js` file. 1. In the CodeLens indicator that identifies an eligible Lambda function handler, choose `Add Debug Configuration`. ![\[Access the Add Debug Configuration option in the CodeLens indicator for a Lambda function handler.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/sam-codelens-lambda.png) 1. In the **Command Palette**, select the runtime in which your AWS SAM application will run. 1. In the editor for the `launch.json` file, edit or confirm values for the following configuration properties: + `"name"` – Enter a reader-friendly name to appear in the **Configuration** dropdown field in the **Run** view. + `"target"` – Ensure that the value is `"code"` so that a Lambda function handler is directly invoked. + `"lambdaHandler"` – Enter the name of the method within your code that Lambda calls to invoke your function. For example, for applications in JavaScript, the default is `app.lambdaHandler`. + `"projectRoot"` – Enter the path to the application file that contains the Lambda function. + `"runtime"` – Enter or confirm a valid runtime for the Lambda execution environment, for example, `"nodejs.12x"`. + `"payload"` – Choose one of the following options to define the event payload that you want to provide to your Lambda function as input: + `"json"`: JSON-formatted key-value pairs that define the event payload. + `"path"`: A path to the file that's used as the event payload. In the example below, the `"json"` option defines the payload. ![\[Configuring the launch.json file for directly invoking Lambda functions.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/direct_invoke_config_updated_with_payload_field.png) For more information about these and other entries in the `launch.json` file, see [Configuration options for debugging serverless applications](serverless-apps-run-debug-config-ref.md). 1. If you're satisfied with the debug configuration, to start debugging, choose the green play arrow next to **RUN**. When the debugging sessions starts, the **DEBUG CONSOLE** panel shows debugging output and displays any values that the Lambda function returns. (When debugging AWS SAM applications, **AWS Toolkit** is selected as the **Output** channel in the **Output** panel.) # Running and debugging local Amazon API Gateway resources You can run or debug AWS SAM API Gateway local resources, specified in `template.yaml`, by running a VS Code launch config of `type=aws-sam` with the `invokeTarget.target=api`. **Note** API Gateway supports two types of APIs, REST and HTTP. However, the API Gateway feature with the AWS Toolkit for Visual Studio Code only supports REST APIs. Sometimes HTTP APIs are called "API Gateway V2 APIs." **To run and debug local API Gateway resources** 1. Choose one of the following approaches to create a launch config for an AWS SAM API Gateway resource: + **Option 1:** Visit the handler source code (.js, .cs, or .py file) in your AWS SAM project, hover over the Lambda handler, and choose the **Add Debug Configuration** CodeLens. Then, in the menu, choose the item marked **API Event**. + **Option 2:** Edit `launch.json` and create a new launch configuration using the following syntax. ``` { "type": "aws-sam", "request": "direct-invoke", "name": "myConfig", "invokeTarget": { "target": "api", "templatePath": "n12/template.yaml", "logicalId": "HelloWorldFunction" }, "api": { "path": "/hello", "httpMethod": "post", "payload": { "json": {} } }, "sam": {}, "aws": {} } ``` 1. In the VS Code **Run** panel, choose the launch config (named `myConfig` in the above example). 1. (Optional) Add breakpoints to your Lambda project code. 1. Type **F5** or choose **Play** in the **Run** panel. 1. In the output pane, view the results. ## Configuration When you use the `invokeTarget.target` property value `api`, the Toolkit changes the launch configuration validation and behavior to support an `api` field. ``` { "type": "aws-sam", "request": "direct-invoke", "name": "myConfig", "invokeTarget": { "target": "api", "templatePath": "n12/template.yaml", "logicalId": "HelloWorldFunction" }, "api": { "path": "/hello", "httpMethod": "post", "payload": { "json": {} }, "querystring": "abc=def&qrs=tuv", "headers": { "cookie": "name=value; name2=value2; name3=value3" } }, "sam": {}, "aws": {} } ``` Replace the values in the example as follows: **invokeTarget.logicalId** An API resource. **path** The API path that the launch config requests, for example, `"path": "/hello"`. Must be a valid API path resolved from the `template.yaml` specified by `invokeTarget.templatePath`. **httpMethod** One of the following verbs: "delete", "get", "head", "options", "patch", "post", "put". **payload** The JSON payload (HTTP body) to send in the request , with the same structure and rules as the [lambda.payload](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html) field. `payload.path` points to a file containing the JSON payload. `payload.json` specifies a JSON payload inline. **headers** Optional map of name-value pairs, which you use to specify HTTP headers to include in the request, as shown in the following example. ``` "headers": { "accept-encoding": "deflate, gzip;q=1.0, *;q=0.5", "accept-language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5", "cookie": "name=value; name2=value2; name3=value3", "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36", } ``` **querystring** Optional string which sets the `querystring` of the request, for example, `"querystring": "abc=def&ghi=jkl"`. **AWS** How AWS connection information is provided. For more information, see the **AWS connection ("aws") properties** table in the [Configuration options for debugging serverless applications](serverless-apps-run-debug-config-ref.md) section. **sam** How the AWS SAM CLI builds the application. For more information, see the **AWS SAM CLI ("sam") properties** table in the [Configuration options for debugging serverless applications](serverless-apps-run-debug-config-ref.md) section. # Configuration options for debugging serverless applications When you open the `launch.json` file to edit debug configurations, you can use the VS Code [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) feature to view and automatically complete valid properties. To trigger IntelliSense in the editor, press **Ctrl**\$1**Spacebar**. ![\[Using VS Code's IntelliSense to find and complete valid debug properties.\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/images/Intellisense_autocomplete.gif) IntelliSense enables you to find and define properties for invoking Lambda functions directly or with the AWS SAM template. You can also define properties for `"lambda"` (how the function runs), `"sam"` (how the AWS SAM CLI builds the application), and `"aws"` (how AWS connection information is provided). **AWS SAM: Direct Lambda handler invoke / Template-based Lambda invoke** | Property | Description | | --- | --- | | `type` | Specifies which extension manages the launch configuration. Always set to `aws-sam` to use the AWS SAM CLI to build and debug locally. | | `name` | Specifies a reader-friendly name to appear in the **Debug launch configuration** list. | | `request` | Specifies the type of configuration to be performed by the designated extension (`aws-sam`). Always set to `direct-invoke` to start the Lambda function. | | `invokeTarget` | Specifies the entry point for invoking the resource. For invoking the Lambda function directly, set values for the following `invokeTarget` fields: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html) For invoking the Lambda resources with the AWS SAM template, set values for the following `invokeTarget` fields: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html) | **Lambda (`"lambda"`) properties** | Property | Description | | --- | --- | | `environmentVariables` | Passes operational parameters to your Lambda function. For example, if you're writing to an Amazon S3 bucket, instead of hard-coding the bucket name that you're writing to, configure the bucket name as an environment variable. When specifying environment variables for a serverless application, you must add configurations to both the AWS SAM template (`template.yaml`) and the `launch.json` file. Example of formatting for an environment variable in the AWS SAM template: 
Resources:
 HelloWorldFunction:
 Type: AWS::Serverless::Function
 Properties:
   CodeUri: hello-world/
   Handler: app.lambdaHandlerN10
   Runtime: nodejs10.x
   Environment:
     Variables:
       SAMPLE1: Default Sample 1 Value
Example of formatting for an environment variable in the `launch.json` file: 
"environmentVariables": {
    "SAMPLE1": "My sample 1 value"
 }
| | `payload` | Provides two options for the event payload that you provide to your Lambda function as input. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html) | | `memoryMB` | Specifies megabytes (MB) of memory provided for running an invoked Lambda function. | | `runtime` | Specifies the runtime that the Lambda function uses. For more information, see [AWS Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). | | `timeoutSec` | Sets the time allowed, in seconds, before the debug session times out. | | `pathMappings` | Specifies where local code is in relation to where it runs in the container. By default, the Toolkit for VS Code sets `localRoot` to the Lambda function's code root in the local workspace, and `remoteRoot` to `/var/task`, which is the default working directory for code running in Lambda. If the working directory is changed in the Dockerfile or with the `WorkingDirectory` parameter in the CloudFormation template file, at least one `pathMapping` entry must be specified so that the debugger can successfully map locally set breakpoints to the code running in the Lambda container. Example of formatting for `pathMappings` in the `launch.json` file: 
"pathMappings": [
    {
        "localRoot": "${workspaceFolder}/sam-app/HelloWorldFunction",
        "remoteRoot": "/var/task"
    }
]
Caveats: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html) | The Toolkit for VS Code uses the AWS SAM CLI to build and debug serverless applications locally. You can configure the behavior of AWS SAM CLI commands using properties of the `"sam"` configuration in the `launch.json` file. **AWS SAM CLI (`"sam"`) properties** | Property | Description | Default value | | --- | --- | --- | | `buildArguments` | Configures how the `sam build` command builds your Lambda source code. To view build options, see [sam build](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html) in the *AWS Serverless Application Model Developer Guide*. | Empty string | | `containerBuild` | Indicates whether to build your function inside a Lambda-like Docker container. | `false` | | `dockerNetwork` | Specifies the name or ID of an existing Docker network that the Lambda Docker containers should connect to, along with the default bridge network. If not specified, the Lambda containers connect only to the default bridge Docker network. | Empty string | | `localArguments` | Specifies additional local invoke arguments. | Empty string | | `skipNewImageCheck` | Specifies whether the command should skip pulling down the latest Docker image for Lambda runtime. | `false` | | `template` | Customizes your AWS SAM template using parameters to input customer values. For more information, see [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) in the *AWS CloudFormation User Guide*. | `"parameters":{}` | **AWS connection (`"aws"`) properties** | Property | Description | Default value | | --- | --- | --- | | `credentials` | Selects a specific profile (for example, `profile:default`) from your credential file to get AWS credentials. | The AWS credentials that your existing [shared AWS config file or shared AWS credentials file](setup-credentials.md) provide to the Toolkit for VS Code. | | `region` | Sets the AWS Region of the service (for example, us-east-1). | The default AWS Region associated with the active credentials profile. | ## Example: Template launch configuration Here is an example launch configuration file for an AWS SAM template target: ``` { "configurations": [ { "type": "aws-sam", "request": "direct-invoke", "name": "my-example:HelloWorldFunction", "invokeTarget": { "target": "template", "templatePath": "template.yaml", "logicalId": "HelloWorldFunction" }, "lambda": { "payload": {}, "environmentVariables": {} } } ] } ``` ## Example: Code launch configuration Here is an example launch configuration file for a Lambda function target: ``` { "configurations": [ { "type": "aws-sam", "request": "direct-invoke", "name": "my-example:app.lambda_handler (python3.7)", "invokeTarget": { "target": "code", "projectRoot": "hello_world", "lambdaHandler": "app.lambda_handler" }, "lambda": { "runtime": "python3.7", "payload": {}, "environmentVariables": {} } } ] } ``` # Troubleshooting serverless applications This topic details common errors that you might encounter when creating serverless applications with the Toolkit for VS Code and how to resolve them. **Topics** + [How can I use a samconfig.toml with a SAM launch configuration?](#troubleshooting-samconfig-toml) + [Error: "RuntimeError: Container does not exist"](#troubleshooting-container-does-not-exist) + [Error: "docker.errors.APIError: 500 Server Error ... You have reached your pull rate limit."](#troubleshooting-reached-rate-limit) + [Error: "500 Server Error: Mounting C:\$1Users\$1..."](#troubleshooting-mounting-error) + [Using WSL, webviews (for example, the "Invoke on AWS" form) are broken](#troubleshooting-broken-webviews) + [Debugging a TypeScript application, but breakpoints are not working](#troubleshooting-typescript-debugging) ## How can I use a samconfig.toml with a SAM launch configuration? Specify the location of your SAM CLI [samconfig.toml](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-config.html) by configuring the `--config-file` argument in the `sam.localArguments` property of your launch configuration. For example, if the samconfig.toml file is located at the top level of your workspace: ``` "sam": { "localArguments": ["--config-file", "${workspaceFolder}/samconfig.toml"], } ``` ## Error: "RuntimeError: Container does not exist" The `sam build` command can show this error if your system does not have enough disk space for the Docker container. If your system storage has only 1-2 GB of space available, `sam build` might fail during processing, even if system storage is not completely full before the build starts. For more information, see [this GitHub issue](https://github.com/aws/aws-sam-cli/issues/2121). ## Error: "docker.errors.APIError: 500 Server Error ... You have reached your pull rate limit." Docker Hub limits requests that anonymous users can make. If your system reaches the limit, Docker fails and this error appears in the OUTPUT view of VS Code: ``` docker.errors.APIError: 500 Server Error: Internal Server Error ("toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit") ``` Ensure that your system Docker service has authenticated with your Docker Hub credentials. ## Error: "500 Server Error: Mounting C:\$1Users\$1..." Windows users might see this Docker mounting error when debugging AWS SAM applications: ``` Fetching lambci/lambda:nodejs10.x Docker container image...... 2019-07-12 13:36:58 Mounting C:\Users\\AppData\Local\Temp\ ... as /var/task:ro,delegated inside runtime container Traceback (most recent call last): ... requests.exceptions.HTTPError: 500 Server Error: Internal Server Error ... ``` Try refreshing the credentials for your shared drives (in the Docker settings). ## Using WSL, webviews (for example, the "Invoke on AWS" form) are broken This is a known VS Code issue for users of Cisco VPN. For more information, see [this GitHub issue](https://github.com/aws/aws-toolkit-vscode/issues/1327). A workaround is suggested in [this WSL tracking issue](https://github.com/microsoft/WSL/issues/4277). ## Debugging a TypeScript application, but breakpoints are not working This will happen if there isn't a source map to link the compiled JavaScript file to the source TypeScript file. To correct this, open your `tsconfig.json` file and ensure the following option and value are set: `"inlineSourceMap": true`.