Debug Serverless Applications Using AWS SAM Local
This tutorial guides you through debugging a serverless application project with the Toolkit for Eclipse
using AWS SAM Local. SAM Local is the AWS CLI tool for managing serverless applications
written with the AWS Serverless Application Model (AWS SAM). See the SAM Local README
Prerequisites
To use this tutorial, you must have the Toolkit for Eclipse, Docker, and AWS SAM Local installed. See
the AWS SAM Local README
To use the AWS SAM Local feature of the Toolkit for Eclipse, your project must be a valid Maven Project with a valid pom.xml file.
After you install the required tools, open the Eclipse Preferences dialog box from the Eclipse menu. Configure the SAM Local Executable path, as shown. This enables the Toolkit for Eclipse to know where to find your SAM Local installation.

Import the SAM Application from AWS CodeStar
For this tutorial, you need a sample project in AWS CodeStar. See the Creating a Serverless Project in AWS CodeStar tutorial in the AWS CodeStar User Guide to create a sample project.
To import SAM app from AWS CodeStar
-
On the Eclipse toolbar, open the Amazon Web Services menu (identified by the AWS homepage icon), and then choose Import AWS CodeStar Project. Or, on the Eclipse menu bar, choose File, Import, AWS, AWS CodeStar Project.
-
Choose the region that the sample application was created in.
-
Choose your sample project from the Project Name list.
-
Add in your Git credentials. See the AWS CodeCommit User Guide to learn how to get Git credentials for CodeCommit.
-
Choose Next.
-
Choose Next on the Branch Selection page.
-
Choose Finish on the Local Destination page.
Next, you can debug this serverless application locally using SAM Local within Eclipse.
Debug Lambda Function Locally
Create a debug configuration for your serverless application and use SAM Local to run the application locally.
To debug the Lambda function locally
-
In the Eclipse Project Explorer, open
HelloWorldHandler.java
. -
Right-click in your Eclipse code window, choose Debug As, and then choose AWS SAM Local.
-
For this example, leave the Project and Template as they are.
-
Choose Lambda Function in the Run as field.
-
Choose GetHelloWorld in the Function identifier field.
-
For this example, we will provide an Amazon S3 event. Choose Generate next to the Event input box.
-
Choose a region that has your Amazon S3 bucket.
-
Enter a valid Amazon S3 bucket name.
-
Enter a valid Amazon S3 object key, and then choose OK.
-
On the Save As page, select the current project and enter a name for the event file. In this example, we used s3-event.json.
-
Choose OK to save the event file and get back to the main dialog box.
-
Leave the advanced settings as they are. See Advanced Settings to learn more about those fields.
-
Choose Apply, and then choose Debug.
This runs the Lambda function locally. You can set breakpoints as you would for other applications to debug the code.
Test API Gateway Locally
You can also test the HTTP request/response functionality with SAM Local.
To test API Gateway locally
-
Right-click in your Eclipse code window, choose Debug As, Debug Configuration.
-
Create a new Debug Configuration for this run and name it something different.
-
Choose API Gateway in the Run as field.
-
Leaving all other fields as they are, your configuration should look similar to the following.
-
Choose Apply, and then choose Debug.
This spawns a local API gateway that you can use to test your application. The debug output will contain HTTP links that can be used to verify the request/response functionality of your code.

Advanced Settings
This section describes the advanced options available on the SAM Local Debug configurations page.

AWS Configuration
- Select profile
-
(Required) The profile to use for AWS credentials.
(Default) The default profile
- Select region
-
(Required) The region that the application is deployed to.
(Default) US East (Virginia)
SAM Local Configuration
- Maven goals
-
(Required) Maven goals to execute when building the application. You must customize these goals if the default does not generate a Jar file with all the dependencies included (fat Jar). See Maven Shade Plugin
in Maven Project to learn how to use the plugin to create a fat Jar. (Default) clean package
- SAM runtime
-
(Required) Path to the SAM executable.
(Default) /usr/local/bin/sam
- Debug port
-
(Required) Port that the Eclipse debugger uses to connect to SAM Local.
(Default) 5858
- Env vars
-
(Optional) Path to a JSON file that contains values for environment variables used by Lambda functions. See Environment variable files
in the SAM Local user guide to learn the required syntax for this file. (Default) Empty
Lambda Function Configuration
- Code URI
-
(Optional) Path to the code archive file. For the example on this page, it would be the path to the .jar file.
(Default) Path in the template.yml file
- Timeout
-
(Required) Lambda function runtime timeout.
(Default) 300
More Info
For more information about AWS SAM Local, see the AWS SAM Local