Lambda

AWS Lambda is a Serverless Function as a Service (FaaS) platform that lets you run code in your preferred programming language on the AWS ecosystem. AWS Lambda automatically scales your code to meet demand and handles server provisioning, management, and maintenance. AWS Lambda allows you to break down your application into smaller, independent functions that integrate seamlessly with AWS services.

LocalStack allows you to use the Lambda APIs to create, deploy, and test your Lambda functions. The supported APIs are available on our API coverage section, which provides information on the extent of Lambda’s integration with LocalStack.

This guide is designed for users new to Lambda and assumes basic knowledge of the AWS CLI and our lstk aws command.

Start your LocalStack container using your preferred method. We will demonstrate how to create a Lambda function with a Function URL. With the Function URL property, you can call a Lambda Function via an HTTP API call.

To create a new Lambda function, create a new file called index.js with the following code:

exports.handler = async (event) => {
    let body = JSON.parse(event.body)
    const product = body.num1 * body.num2;
    const response = {
        statusCode: 200,
        body: "The product of " + body.num1 + " and " + body.num2 + " is " + product,
    };
    return response;
};

Enter the following command to create a new Lambda function:

zip function.zip index.js
lstk aws lambda create-function \
    --function-name localstack-lambda-url-example \
    --runtime nodejs22.x \
    --zip-file fileb://function.zip \
    --handler index.handler \
    --role arn:aws:iam::000000000000:role/lambda-role

To invoke the Lambda function, you can use the Invoke API. Run the following command to invoke the function:

lstk aws lambda invoke --function-name localstack-lambda-url-example \
    --payload '{"body": "{\"num1\": \"10\", \"num2\": \"10\"}" }' output.txt

lstk aws lambda invoke --function-name localstack-lambda-url-example \
    --cli-binary-format raw-in-base64-out \
    --payload '{"body": "{\"num1\": \"10\", \"num2\": \"10\"}" }' output.txt

With the Function URL property, there is now a new way to call a Lambda Function via HTTP API call using the CreateFunctionURLConfig API. To create a URL for invoking the function, run the following command:

lstk aws lambda create-function-url-config \
    --function-name localstack-lambda-url-example \
    --auth-type NONE

This will generate a HTTP URL that can be used to invoke the Lambda function. The URL will be in the format http://<XXXXXXXX>.lambda-url.us-east-1.localhost.localstack.cloud:4566.

You can now trigger the Lambda function by sending a HTTP POST request to the URL using curl or your REST HTTP client:

curl -X POST \
    'http://<XXXXXXXX>.lambda-url.us-east-1.localhost.localstack.cloud:4566/' \
    -H 'Content-Type: application/json' \
    -d '{"num1": "10", "num2": "10"}'

The product of 10 and 10 is 100%

Lambda event source mappings allows you to connect Lambda functions to other AWS services. The following event sources are supported in LocalStack:

• Simple Queue Service (SQS)
• DynamoDB
• Kinesis
• Managed Streaming for Apache Kafka (MSK) ⭐️
• Self-Managed Apache Kafka ⭐️

The table below shows feature coverage for all supported event sources for the latest version of LocalStack.

Unlike API operation coverage, this table illustrates the functional and behavioural coverage of LocalStack’s Lambda Event Source Mapping implementation.

Where necessary, footnotes are used to provide additional context.

Create a GitHub Discussion or reach out to LocalStack Support if you experience any challenges.

Lambda layers let you include additional code and dependencies in your Lambda functions. With a valid LocalStack license, you can deploy Lambda Layers locally to streamline your development and testing process.

To create a Lambda Layer locally, you can use the PublishLayerVersion API in LocalStack. Here’s a simple example using Python:

mkdir -p /tmp/python/
echo 'def util():' > /tmp/python/testlayer.py
echo '  print("Output from Lambda layer util function")' >> /tmp/python/testlayer.py
(cd /tmp; zip -r testlayer.zip python)
LAYER_ARN=$(lstk aws lambda publish-layer-version --layer-name layer1 --zip-file fileb:///tmp/testlayer.zip | jq -r .LayerVersionArn)

Next, define a Lambda function that uses our layer:

echo 'def handler(*args, **kwargs):' > /tmp/testlambda.py
echo '  import testlayer; testlayer.util()' >> /tmp/testlambda.py
echo '  print("Debug output from Lambda function")' >> /tmp/testlambda.py
(cd /tmp; zip testlambda.zip testlambda.py)
lstk aws lambda create-function \
  --function-name func1 \
  --runtime python3.8 \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --handler testlambda.handler \
  --timeout 30 \
  --zip-file fileb:///tmp/testlambda.zip \
  --layers $LAYER_ARN

Here, we’ve defined a Lambda function called handler() that imports the util() function from our layer1 Lambda Layer. We then used the CreateFunction API to create this Lambda function in LocalStack, specifying the layer1 Lambda Layer as a dependency.

To test our Lambda function and see the output from the Lambda Layer, we can invoke the function and check the logs (with DEBUG=1 enabled). Here’s an example:

> START RequestId: a8bc4ce6-e2e8-189e-cf58-c2eb72827c23 Version: $LATEST
> Output from Lambda layer util function
> Debug output from Lambda function
> END RequestId: a8bc4ce6-e2e8-189e-cf58-c2eb72827c23

If your Lambda function references a layer in real AWS, you can integrate it into your local dev environment by making it accessible to the 886468871268 AWS account ID. This account is managed by LocalStack on AWS.

To grant access to your layer, run the following command:

aws lambda add-layer-version-permission \
  --layer-name test-layer \
  --version-number 1 \
  --statement-id layerAccessFromLocalStack \
  --principal 886468871268 \
  --action lambda:GetLayerVersion

Replace test-layer and 1 with the name and version number of your layer, respectively.

After granting access, the next time you reference the layer in one of your local Lambda functions using the AWS Lambda layer ARN, the layer will be automatically pulled down and integrated into your local dev environment.

Lambda functions can mount S3 Files access points through FileSystemConfigs. See Mounting a file system from Lambda for the requirements and an example.

LocalStack provides local testing support for Lambda Managed Instances. We support all of the new APIs, as well as the CloudFormation and Terraform resource types. All the same configuration is therefore possible on your local machine, without needing to modify your infrastructure as code (IaC).

Lambda Durable Functions run checkpointed, replayable workflows that can continue for up to one year. LocalStack supports durable executions for Node.js 22 and 24, Python 3.13 and 3.14, Java 17, 21, and 25, and .NET 8 and 10.

Install the JavaScript durable execution SDK and include it with the function’s deployment package:

npm install --silent @aws/durable-execution-sdk-js
zip -qr function.zip index.mjs node_modules package.json package-lock.json

Create index.mjs with a checkpointed step followed by a one-second durable wait:

1
import { withDurableExecution } from "@aws/durable-execution-sdk-js";
2

3
export const handler = withDurableExecution(async (event, context) => {
4
  const result = await context.step(async () => ({
5
    message: `Hello, ${event.name}!`,
6
  }));
7

8
  await context.wait({ seconds: 1 });
9
  return result;
10
});

Create the function with a five-minute execution timeout and seven-day retention period:

lstk aws lambda create-function \
  --function-name durable-hello \
  --runtime nodejs22.x \
  --handler index.handler \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --zip-file fileb://function.zip \
  --timeout 30 \
  --durable-config '{"ExecutionTimeout":300,"RetentionPeriodInDays":7}'

{
  "FunctionName": "durable-hello",
  "FunctionArn": "arn:aws:lambda:us-east-1:000000000000:function:durable-hello",
  "Runtime": "nodejs22.x",
  "State": "Pending",
  "DurableConfig": {
    "RetentionPeriodInDays": 7,
    "ExecutionTimeout": 300
  }
}

Wait for the function to become active:

lstk aws lambda wait function-active-v2 --function-name durable-hello

Create event.json:

{
  "name": "LocalStack"
}

Start an asynchronous durable execution. Use a qualified function target and a durable execution name, which acts as an idempotency key:

EXECUTION_ARN=$(lstk aws lambda invoke \
  --function-name durable-hello \
  --qualifier '$LATEST' \
  --invocation-type Event \
  --durable-execution-name hello-docs \
  --payload fileb://event.json \
  response.json \
  | jq -r '.DurableExecutionArn')
echo "$EXECUTION_ARN"

arn:aws:lambda:us-east-1:000000000000:function:durable-hello:$LATEST/durable-execution/hello-docs/<execution-id>

After the execution finishes, retrieve its status and result:

lstk aws lambda get-durable-execution \
  --durable-execution-arn "$EXECUTION_ARN" \
  --query '{DurableExecutionName:DurableExecutionName,Status:Status,Result:Result,DurableConfig:DurableConfig}'

{
  "DurableExecutionName": "hello-docs",
  "Status": "SUCCEEDED",
  "Result": "{\"message\":\"Hello, LocalStack!\"}",
  "DurableConfig": {
    "RetentionPeriodInDays": 7,
    "ExecutionTimeout": 300
  }
}

Inspect the execution history to see the checkpoint, suspension, replay, and completion:

lstk aws lambda get-durable-execution-history \
  --durable-execution-arn "$EXECUTION_ARN" \
  --query 'Events[].EventType'

[
  "ExecutionStarted",
  "StepStarted",
  "StepSucceeded",
  "WaitStarted",
  "InvocationCompleted",
  "WaitSucceeded",
  "InvocationCompleted",
  "ExecutionSucceeded"
]

LocalStack supports the following durable workflow behaviors:

• Synchronous and asynchronous durable invocations with named, idempotent executions.
• Checkpointed steps, waits, condition polling, and step retries.
• Callbacks with heartbeats, success and failure responses, and restart-safe timeouts.
• Chained Lambda invocations, parallel branches, maps, and child contexts.
• Execution history, stopping and draining executions, retention, persistence, and asynchronous dead-letter queue delivery.
• Function URL and event source mapping dispatch to durable functions, subject to the AWS execution-time constraints.

LocalStack currently has the following limitations:

• KMSKeyArn is validated, stored, merged, and returned, but LocalStack does not use the key to encrypt durable execution data.
• LocalStack does not emit durable execution monitoring events to CloudWatch or EventBridge.
• LocalStack does not enforce API request-per-second throttling or the account-level running-executions quota.
• LocalStack enforces the checkpoint protocol limits, including 3,000 operations and 100 MB of written state per execution.

Lambda Debug Mode supports durable executions. Replays use the debug environment pinned to the execution, and LocalStack defers ExecutionTimeout while execution is paused at a breakpoint.

LocalStack uses a custom implementation of the AWS Lambda Runtime Interface Emulator to match the behavior of AWS Lambda as closely as possible while providing additional features such as hot reloading. We ship our custom implementation as a Golang binary, which gets copied into each Lambda container under /var/rapid/init. This init binary is used as the entry point for every Lambda container.

Our custom implementation offers additional configuration options, but these configurations are primarily intended for LocalStack developers and could change in the future. The LocalStack configuration LAMBDA_DOCKER_FLAGS can be used to configure all Lambda containers, for example LAMBDA_DOCKER_FLAGS=-e LOCALSTACK_INIT_LOG_LEVEL=debug. Some noteworthy configurations include:

• LOCALSTACK_INIT_LOG_LEVEL defines the log level of the Golang binary. Values: trace, debug, info, warn (default), error, fatal, panic
• LOCALSTACK_USER defines the system user executing the Lambda runtime. Values: sbx_user1051 (default), root (skip dropping root privileges)

The full list of configurations is defined in the Golang function InitLsOpts.

Lambda execution environments communicate back to the LocalStack container for runtime APIs, credentials, logs, and calls to emulated AWS services. If your host, Docker daemon, or Kubernetes cluster injects http_proxy or https_proxy into Lambda containers, that internal traffic must bypass the proxy.

LocalStack automatically adds the configured LOCALSTACK_HOST host, and the runtime LOCALSTACK_HOSTNAME when present, to the Lambda execution environment’s no_proxy variable. If your function already defines no_proxy, LocalStack preserves the existing entries and prepends the LocalStack hosts.

In Kubernetes deployments, make sure admission controllers or proxy-injection policies do not overwrite the no_proxy value after LocalStack creates Lambda pods. If your cluster-level policy manages no_proxy, include the LocalStack host used by your deployment, for example localhost.localstack.cloud or the host configured through LOCALSTACK_HOST.

LocalStack provides various tools to help you develop, debug, and test your AWS Lambda functions more efficiently.

• Hot reloading: With Lambda hot reloading, you can continuously apply code changes to your Lambda functions without needing to redeploy them manually. To learn more about how to use hot reloading with LocalStack, check out our hot reloading documentation.
• Remote debugging: LocalStack’s remote debugging functionality allows you to attach a debugger to your Lambda function using your preferred IDE. To get started with remote debugging in LocalStack, see our debugging documentation.
• Lambda VS Code Extension: LocalStack’s Lambda VS Code Extension supports deploying and invoking Python Lambda functions through AWS SAM or AWS CloudFormation. To get started with the Lambda VS Code Extension, see our Lambda VS Code Extension documentation.
• API for querying Lambda runtimes: LocalStack offers a metadata API to query the list of Lambda runtimes via GET http://localhost.localstack.cloud:4566/_aws/lambda/runtimes. It returns the Supported Runtimes matching AWS parity (i.e., excluding deprecated runtimes) and offers additional filters for deprecated runtimes and all runtimes (GET /_aws/lambda/runtimes?filter=all).

The LocalStack Web Application provides a Resource Browser for managing Lambda resources. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the Resources section, and then clicking on Lambda under the Compute section.

The Resource Browser displays Functions and Layers resources. You can click on individual resources to view their details.

The Resource Browser allows you to perform the following actions:

• Create Functions & Layers: Create a new Lambda function or a new Lambda Layer by clicking on Create API button on top-right and creating a new configuration by clicking on Submit button.
• View Function & Layer Details: Click on any function or layer to view detailed information such as the resource’s name, ARN, runtime, handler, and more. You can also navigate across different versions of the resource.
• Delete Functions & Layers: To delete a function or layer, select the resource from the Resource Browser, click on the Remove Selected button at the top-right of the screen, and confirm the deletion by clicking on the Continue button.

As part of the LocalStack 2.0 release, the Lambda provider has been migrated to v2 (formerly known as asf). With the new implementation, the following changes have been introduced:

• To run Lambda functions in LocalStack, mount the Docker socket into the LocalStack container. Add the following Docker volume mount to your LocalStack startup configuration: /var/run/docker.sock:/var/run/docker.sock. You can find an example of this configuration in our official docker-compose.yml file.
• The v2 provider discontinues Lambda Executor Modes such as LAMBDA_EXECUTOR=local. Previously, this mode was used as a fallback when the Docker socket was unavailable in the LocalStack container, but many users unintentionally used it instead of the configured LAMBDA_EXECUTOR=docker. The new provider now behaves similarly to the old docker-reuse executor and does not require such configuration.
• The Lambda containers are now reused between invocations. The changes made to the filesystem (such as in /tmp) will persist between subsequent invocations if the function is dispatched to the same container. This is known as a warm start (see Operating Lambda for more information). To ensure that each invocation starts with a fresh container, you can set the LAMBDA_KEEPALIVE_MS configuration option to 0 milliseconds, to force cold starts.
• The platform uses official Docker base images pulled from public.ecr.aws/lambda/, instead of lambci, and supports both arm64 and x86_64 architectures. The Lambda functions filesystem now matches the AWS Lambda production environment. The ARM containers for compatible runtimes are based on Amazon Linux 2, and ARM-compatible hosts can create functions with the arm64 architecture.
• Lambda functions in LocalStack resolve AWS domains, such as s3.amazonaws.com, to the LocalStack container. This domain resolution is DNS-based and can be disabled by setting DNS_ADDRESS=0. For more information, refer to Transparent Endpoint Injection. Previously, LocalStack provided patched AWS SDKs to redirect AWS API calls transparently to LocalStack.
• The new provider may generate more exceptions due to invalid input. For instance, while the old provider accepted arbitrary strings (such as r1) as Lambda roles when creating a function, the new provider validates role ARNs using a regular expression that requires them to be in the format arn:aws:iam::000000000000:role/lambda-role. However, it currently does not verify whether the role actually exists.
• The new Lambda provider now follows the AWS Lambda state model, while creating and updating Lambda functions, which allows for asynchronous processing. Functions are always created in the Pending state and move to Active once they are ready to accept invocations. Previously, the functions were created synchronously by blocking until the function state was active. The configuration LAMBDA_SYNCHRONOUS_CREATE=1 can force synchronous function creation, but it is not recommended.
• LocalStack’s Lambda implementation, allows you to customize the Lambda execution environment using the Lambda Extensions API. This API allows for advanced monitoring, observability, or developer tooling, providing greater control and flexibility over your Lambda functions. Lambda functions can also be run on hosts with multi-architecture support, allowing you to leverage LocalStack’s Lambda API to develop and test Lambda functions with high parity.

The following configuration options from the old provider are discontinued in the new provider:

• The LAMBDA_EXECUTOR and specifically, the LAMBDA_EXECUTOR=local options are no longer supported.
• The LAMBDA_STAY_OPEN_MODE is now the default behavior and can be removed. Instead, use the LAMBDA_KEEPALIVE_MS option to configure how long containers should be kept running in between invocations.
• The LAMBDA_REMOTE_DOCKER option is not used anymore since the new provider automatically copies zip files and configures hot reloading.
• The LAMBDA_CODE_EXTRACT_TIME option is no longer used because function creation is now asynchronous.
• The LAMBDA_FALLBACK_URL, SYNCHRONOUS_KINESIS_EVENTS, SYNCHRONOUS_SNS_EVENTS and LAMBDA_FORWARD_URL options are currently not supported.
• The LAMBDA_CONTAINER_REGISTRY option is not used anymore. Instead, use the more flexible LAMBDA_RUNTIME_IMAGE_MAPPING option to customize individual runtimes.
• The LAMBDA_XRAY_INIT option is no longer needed because the X-Ray daemon is always initialized.

However, the new provider still supports the following configuration options:

• The BUCKET_MARKER_LOCAL option has a new default value, hot-reload. The former default value __local__ is an invalid bucket name.
• The LAMBDA_TRUNCATE_STDOUT option.
• The LAMBDA_DOCKER_NETWORK option.
• The LAMBDA_DOCKER_FLAGS option.
• The LAMBDA_REMOVE_CONTAINERS option.
• The LAMBDA_DOCKER_DNS option since LocalStack 2.2.
• The HOSTNAME_FROM_LAMBDA option since LocalStack 3.0.

The following code snippets and sample applications provide practical examples of how to use Lambda in LocalStack for various use cases:

• Lambda Debugging demonstrates how to remotely debug a Lambda function from within your IDE.
  • Debug your Python Lambda Function
  • Debug your JavaScript Lambda Function
  • Debug your TypeScript Lambda Function
  • Debug your Java Lambda Function
• Lambda Hot Reloading shows how to use hot reloading to update function code and layers without having to redeploy them.
• Lambda Function URL shows how to use HTTP to invoke a Lambda function via its Function URL.
• Lambda Layers demonstrates how to use Lambda layers, which are reusable packages of code that can be shared across multiple functions.
• Lambda PHP/Bref shows how to use PHP/Bref with and without fpm, using the Serverless framework and AWS CDK.
• Lambda Container Images demonstrates how to use Lambda functions packaged as container images, which can be built using Docker and pushed to a local ECR registry.
• Lambda X-Ray shows how to instrument Lambda functions for X-Ray using Powertools and the X-Ray SDK.

In the old Lambda provider, Lambda functions were executed within the LocalStack container using the local executor mode. This mode was used as a fallback if the Docker socket was unavailable in the LocalStack container. However, many users inadvertently used the local executor mode instead of the intended Docker executor mode, which caused unexpected behavior.

If you encounter the following error message, you may be using the local executor mode:

Lambda 'arn:aws:lambda:us-east-1:000000000000:function:my-function:$LATEST' changed to failed.
Reason: Docker not available
...
raise DockerNotAvailable("Docker not available")

An error occurred (ResourceConflictException) when calling the Invoke operation (reached max retries: 0): The operation cannot be performed at this time.
The function is currently in the following state: Failed

Error: Failed to create/update the stack: sam-app, Waiter StackCreateComplete failed: Waiter encountered a terminal failure state: For expression "Stacks[].StackStatus" we matched expected path: "CREATE_FAILED" at least once

To fix this issue, add the Docker volume mount /var/run/docker.sock:/var/run/docker.sock to your LocalStack startup. Refer to our sample docker-compose.yml file as an example.

If you receive a ResourceConflictException when trying to invoke a function, it is currently in a Pending state and cannot be executed yet.

lstk aws lambda get-function --function-name my-function

An error occurred (ResourceConflictException) when calling the Invoke operation (reached max retries: 0):
The operation cannot be performed at this time.
The function is currently in the following state: Pending

To wait until the function becomes active, you can use the following command:

lstk aws lambda wait function-active-v2 --function-name my-function

Alternatively, you can check the function state using the GetFunction API:

lstk aws lambda get-function --function-name my-function

{
  "Configuration": {
    ...
    "RevisionId": "c61d6139-1441-4ad5-983a-5a1cec7a1847",
    "State": "Pending",
    "StateReason": "The function is being created.",
    "StateReasonCode": "Creating",
    ...
  }
}

When the function is active, the output will be similar to the following:

lstk aws lambda get-function --function-name my-function

{
  "Configuration": {
    ...
    "RevisionId": "c6633a28-b8d2-40f7-b8e1-02f6f32e8473",
    "State": "Active",
    "LastUpdateStatus": "Successful",
    ...
  }
}

If the function is still in the Pending state, the output will include a "State": "Pending" field and a "StateReason": "The function is being created." message. Once the function is active, the "State" field will change to "Active" and the "LastUpdateStatus" field will indicate the status of the last update.

If you are using LocalStack versions prior to 2.0, and encounter a NotImplementedError in the LocalStack logs and an InternalFailure (501) error in the client while creating a Lambda function using the CreateFunction API, check your PROVIDER_OVERRIDE_LAMBDA configuration. You might encounter this error if it is set to legacy.