Invoking Lambda functions locally

You can invoke your AWS Lambda function locally by using the sam local invoke AWS SAM CLI command and providing the function's logical ID and an event file. Alternatively, sam local invoke also accepts stdin as an event. For more information about events, see Event in the AWS Lambda Developer Guide. For information about event message formats from different AWS services, see Using AWS Lambda with other services in the AWS Lambda Developer Guide.

Note

The sam local invoke command corresponds to the AWS Command Line Interface (AWS CLI) command aws lambda invoke. You can use either command to invoke a Lambda function.

You must run the sam local invoke command in the project directory that contains the function that you want to invoke.

Examples:

# Invoking function with event file
$ sam local invoke "Ratings" -e event.json

# Invoking function with event via stdin
$ echo '{"message": "Hey, are you there?" }' | sam local invoke --event - "Ratings"

# For more options
$ sam local invoke --help

Environment variable file

To declare environment variables locally that override values defined in your templates, do the following:

1. Create a JSON file that contains the environment variables to override.

2. Use the --env-vars argument to override values defined in your templates.

Declaring environment variables

To declare environment variables that apply globally to all resources, specify a Parameters object like the following:

{
    "Parameters": {
        "TABLE_NAME": "localtable",
        "BUCKET_NAME": "testBucket",
        "STAGE": "dev"
    }
}

To declare different environment variables for each resource, specify objects for each resource like the following:

{
    "MyFunction1": {
        "TABLE_NAME": "localtable",
        "BUCKET_NAME": "testBucket",
    },
    "MyFunction2": {
        "TABLE_NAME": "localtable",
        "STAGE": "dev"
    }
}

When specifying objects for each resource, you can use the following identifiers, listed in order of highest to lowest precedence:

1. logical_id

2. function_id

3. function_name

4. Full path identifier

You can use both of the preceding methods of declaring environment variables together in a single file. When doing so, environment variables that you provided for specific resources take precedence over global environment variables.

Save your environment variables in a JSON file, such as env.json.

Overriding environment variable values

To override environment variables with those defined in your JSON file, use the --env-vars argument with the invoke or start-api commands. For example:

sam local invoke --env-vars env.json

Layers

If your application includes layers, for information about how to debug issues with layers on your local host, see Working with layers.

Learn more

For a hands-on example of invoking functions locally, see Module 2 - Run locally in The Complete AWS SAM Workshop.