AWS Lambda Durable Functions
AWSOfficialPublished by AWS
- Skill
- Tool integration
- Cloud and DevOps
- Apache-2.0
- Low risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides guidance and patterns for implementing durable, multi-step applications on AWS Lambda. It focuses on the replay model, which allows functions to maintain state across long-running executions—up to one year—by automatically checkpointing progress. The skill covers essential architectural patterns such as the saga pattern for error handling, wait/callback mechanisms for external system integration, and testing strategies using the local test runner. It emphasizes strict adherence to deterministic coding practices required by the replay model to ensure reliable execution.
What it does
- Enables state persistence for long-running Lambda functions.
- Provides patterns for implementing the saga pattern and compensating transactions.
- Supports wait/callback patterns for integrating with external systems.
- Offers guidance on testing durable functions locally and in the cloud.
- Defines rules for deterministic code to prevent state corruption during replays.
- Outlines requirements for qualified ARN invocation and IAM permissions.
When to use it
- When building workflows that require execution times longer than standard Lambda timeouts.
- When orchestrating multi-step processes that need to maintain state across interruptions.
- When implementing reliable, fault-tolerant serverless integrations.
- When managing complex state machines or human-in-the-loop approval processes.
- When you need automatic retry logic and checkpointing for critical business processes.
Advantages
- Resilient execution that survives infrastructure interruptions.
- Simplified state management without external databases for simple workflows.
- Native support for complex orchestration patterns like sagas and parallel execution.
- Built-in replay-aware logging and error handling.
- Local testing capabilities to validate complex workflow logic.
Usage examples
- “How do I implement a multi-step workflow with a wait period in AWS Lambda?”
- The agent provides a code example using context.step for logic and context.wait for the delay, ensuring the execution state is persisted correctly.
- “Why is my durable function failing during replay?”
- The agent helps diagnose non-deterministic code (like Date.now() or Math.random()) placed outside of steps, which causes state corruption.
- “How do I handle errors in a long-running durable function?”
- The agent explains the saga pattern and how to implement compensating transactions within steps to roll back state if a step fails.
- “What are the requirements for invoking a durable Lambda function?”
- The agent clarifies that durable functions must be invoked using a qualified ARN (version, alias, or $LATEST) and provides the corresponding AWS CLI command.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/aws/aws-lambda-durable-functions/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip aws-lambda-durable-functions.zip -d .agents/skills
Documentation by AWS
AWS Lambda durable functions
Build resilient multi-step applications and AI workflows that can execute for up to 1 year while maintaining reliable progress despite interruptions.
Works best with the AWS MCP server but is not required. All AWS interactions in this skill use standard AWS CLI commands that work in any environment with configured AWS credentials.
Critical Rules
Read these before writing any code. Each one is a constraint that will silently break a function if violated.
Durable execution must be enabled at function creation time — it cannot be retrofitted. A new Lambda function must be created with durable execution turned on. Migrate the logic into the new function; do not attempt to install the SDK and wrap the handler of the existing function and expect it to work.
Durable functions must be invoked with a qualified ARN — a specific version, an alias, or the literal
$LATESTsuffix. An unqualified function name will fail. See the Invocation Requirements section below for examples.Durable operations cannot be nested. You cannot call
context.step(),context.wait(), orcontext.invoke()from inside another step's callback. Usecontext.runInChildContext()to group operations instead.All non-deterministic code must run inside steps.
Date.now(),Math.random(), UUID generation, API calls, and database queries outside a step will produce different values on replay and corrupt execution state.Closure mutations are lost on replay - return values from steps
Side effects outside steps repeat - use
context.logger(replay-aware)
When to Load Reference Files
Load the appropriate reference file based on what the user is working on:
Getting started, basic setup, example, ESLint, or Jest setup -> see getting-started.md
Understanding replay model, determinism, or non-deterministic errors -> see replay-model-rules.md
Creating steps, atomic operations, or retry logic -> see step-operations.md
Waiting, delays, callbacks, external systems, or polling -> see wait-operations.md
Parallel execution, map operations, batch processing, or concurrency -> see concurrent-operations.md
Error handling, retry strategies, saga pattern, or compensating transactions -> see error-handling.md
Advanced error handling, timeout handling, circuit breakers, or conditional retries -> see advanced-error-handling.md
Testing, local testing, cloud testing, test runner, or flaky tests -> see testing-patterns.md
Deployment, CloudFormation, CDK, SAM, log groups, deploy, or infrastructure -> see deployment-iac.md
Advanced patterns, GenAI agents, completion policies, step semantics, or custom serialization -> see advanced-patterns.md
troubleshooting, stuck execution, failed execution, debug execution ID, execution history, execution error, why did my execution fail, execution timed out, callback not received, diagnose execution, or root cause execution -> see troubleshooting-executions.md
Quick Reference
Basic Handler Pattern
TypeScript:
import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';
export const handler = withDurableExecution(async (event, context: DurableContext) => {
const result = await context.step('process', async () => processData(event));
return result;
});Python:
from aws_durable_execution_sdk_python import durable_execution, DurableContext
@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
result = context.step(lambda _: process_data(event), name='process')
return resultPython API Differences
The Python SDK differs from TypeScript in several key areas:
Steps: Use
@durable_stepdecorator +context.step(my_step(args)), or inlinecontext.step(lambda _: ..., name='...'). Prefer the decorator for automatic step naming.Wait:
context.wait(duration=Duration.from_seconds(n), name='...')Exceptions:
ExecutionError(permanent),InvocationError(transient),CallbackError(callback failures)Testing: Use
DurableFunctionTestRunnerclass directly - instantiate with handler, use context manager, callrun(input=...)
Invocation Requirements
Durable functions require qualified ARNs (version, alias, or $LATEST):
# Valid
aws lambda invoke --function-name my-function:1 output.json
aws lambda invoke --function-name my-function:live output.json
# Invalid - will fail
aws lambda invoke --function-name my-function output.jsonIAM Permissions
Your Lambda execution role MUST have the AWSLambdaBasicDurableExecutionRolePolicy managed policy attached. This includes:
lambda:CheckpointDurableExecution- Persist execution statelambda:GetDurableExecutionState- Retrieve execution stateCloudWatch Logs permissions
Additional permissions needed for:
Durable invokes:
lambda:InvokeFunctionon target function ARNsExternal callbacks: Systems need
lambda:SendDurableExecutionCallbackSuccessandlambda:SendDurableExecutionCallbackFailure
Validation Guidelines
When writing or reviewing durable function code, ALWAYS check for these replay model violations:
Non-deterministic code outside steps:
Date.now(),Math.random(), UUID generation, API calls, database queries must all be inside stepsNested durable operations in step functions: Cannot call
context.step(),context.wait(), orcontext.invoke()inside a step function — usecontext.runInChildContext()insteadClosure mutations that won't persist: Variables mutated inside steps are NOT preserved across replays — return values from steps instead
Side effects outside steps that repeat on replay: Use
context.loggerfor logging (it is replay-aware and deduplicates automatically)
When implementing or modifying tests for durable functions, ALWAYS verify:
All operations have descriptive names
Tests get operations by NAME, never by index
Replay behavior is tested with multiple invocations
Use
LocalDurableTestRunnerfor local testing
Security Considerations
Checkpoint data encryption: Execution state is persisted automatically. Enable KMS encryption on associated CloudWatch Log Groups to protect checkpointed data at rest.
Sensitive data in step results: Step return values are checkpointed and persisted. Do not return secrets, raw credentials, or PII from steps — store sensitive data in Secrets Manager or SSM Parameter Store and return references instead.
Input validation: Validate and sanitize event payloads at the handler entry point before passing data to steps.
Credential management: Retrieve secrets from AWS Secrets Manager or SSM Parameter Store within steps.
Callback payload validation: Data received via
waitForCallbackoriginates from external systems — validate and sanitize before processing.Logging: Avoid
DEBUGlog level in non-development environments as it may expose step results and execution state. Enable CloudWatch Logs encryption with KMS.
Resources
Files
- ATTRIBUTION.mdAdded by AutoGineer946 B
- LICENSELicence file added by AutoGineer9.9 KiB
- NOTICELicence file added by AutoGineer67 B
- SKILL.md8.9 KiB
- references/advanced-error-handling.md4.9 KiB
- references/advanced-patterns.md10.4 KiB
- references/concurrent-operations.md8.4 KiB
- references/deployment-iac.md14.0 KiB
- references/error-handling.md10.5 KiB
- references/getting-started.md12.6 KiB
- references/replay-model-rules.md8.3 KiB
- references/step-operations.md8.3 KiB
- references/testing-patterns.md17.4 KiB
- references/troubleshooting-executions.md8.5 KiB
- references/wait-operations.md9.5 KiB
references/deployment-iac.md
Deployment with Infrastructure as Code
Deploy durable functions using CloudFormation, CDK, or SAM.
Requirements
All durable functions require:
DurableConfig property on the function
AWSLambdaBasicDurableExecutionRolePolicy attached to execution role
Qualified ARN (version or alias) for invocation
AWS CloudFormation
template.yaml:
AWSTemplateFormatVersion: '2010-09-09'
Resources:
DurableFunctionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: lambda.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
DurableFunction:
Type: AWS::Lambda::Function
Properties:
FunctionName: myDurableFunction
Runtime: nodejs24.x # or python3.14
Handler: index.handler
Role: !GetAtt DurableFunctionRole.Arn
Code:
ZipFile: |
// Your durable function code
DurableConfig:
ExecutionTimeout: 3600 # Max execution time (seconds)
RetentionPeriodInDays: 7 # How long to keep execution state
Environment:
Variables:
LOG_LEVEL: INFO
DurableFunctionVersion:
Type: AWS::Lambda::Version
Properties:
FunctionName: !Ref DurableFunction
DurableFunctionAlias:
Type: AWS::Lambda::Alias
Properties:
FunctionName: !Ref DurableFunction
FunctionVersion: !GetAtt DurableFunctionVersion.Version
Name: live
Outputs:
FunctionArn:
Value: !GetAtt DurableFunction.Arn
AliasArn:
Value: !Ref DurableFunctionAliasDeploy:
aws cloudformation deploy \
--template-file template.yaml \
--stack-name my-durable-function \
--capabilities CAPABILITY_IAMAWS CDK
TypeScript:
import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as iam from 'aws-cdk-lib/aws-iam';
export class DurableFunctionStack extends cdk.Stack {
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
super(scope, id, props);
const durableFunction = new lambda.Function(this, 'DurableFunction', {
runtime: lambda.Runtime.NODEJS_24_X, // or PYTHON_3_14
handler: 'index.handler',
code: lambda.Code.fromAsset('lambda'),
durableConfig: {
executionTimeout: cdk.Duration.hours(1),
retentionPeriod: cdk.Duration.days(7)
},
environment: {
LOG_LEVEL: 'INFO'
}
});
// CDK automatically adds checkpoint permissions when durableConfig is set
// Create version and alias
const version = durableFunction.currentVersion;
const alias = new lambda.Alias(this, 'LiveAlias', {
aliasName: 'live',
version: version
});
// Output the qualified ARN
new cdk.CfnOutput(this, 'FunctionAliasArn', {
value: alias.functionArn
});
}
}Deploy:
cdk deployCDK Custom Log Group Management
Best Practice: Explicitly create and manage CloudWatch Log Groups for better control over retention, cleanup, and costs.
import * as logs from 'aws-cdk-lib/aws-logs';
import * as iam from 'aws-cdk-lib/aws-iam';
// 1. Create explicit log group
const functionLogGroup = new logs.LogGroup(this, 'DurableFunctionLogGroup', {
logGroupName: '/aws/lambda/myDurableFunction',
retention: logs.RetentionDays.ONE_WEEK,
removalPolicy: cdk.RemovalPolicy.DESTROY, // Delete on stack destroy
});
// 2. Link to function
const durableFunction = new lambda.Function(this, 'DurableFunction', {
runtime: lambda.Runtime.NODEJS_24_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('lambda'),
logGroup: functionLogGroup, // Link to managed log group
durableConfig: {
executionTimeout: cdk.Duration.hours(1),
retentionPeriod: cdk.Duration.days(7)
}
});
// 3. Add durable execution policy (required with explicit log groups)
durableFunction.role?.addManagedPolicy(
iam.ManagedPolicy.fromAwsManagedPolicyName(
'service-role/AWSLambdaBasicDurableExecutionRolePolicy'
)
);Benefits:
Explicit Cleanup:
removalPolicy: cdk.RemovalPolicy.DESTROYensures log groups are deleted when stack is destroyedCustom Retention: Set retention periods matching compliance/debugging needs
Predictable Naming: Control exact log group name
Cost Control: Avoid accumulating costs from orphaned log groups
When to use:
✅ Production environments where log retention policies must be enforced
✅ Development/test environments where automatic cleanup saves costs
✅ Multi-function stacks where consistent log management is needed
Important: Don't forget to add AWSLambdaBasicDurableExecutionRolePolicy when using explicit log groups.
AWS SAM
template.yaml:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Globals:
Function:
Timeout: 900
MemorySize: 512
Resources:
DurableFunction:
Type: AWS::Serverless::Function
Properties:
FunctionName: myDurableFunction
Runtime: nodejs24.x # or python3.14
Handler: index.handler
CodeUri: ./src
DurableConfig:
ExecutionTimeout: 3600
RetentionPeriodInDays: 7
Policies:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
AutoPublishAlias: live
Environment:
Variables:
LOG_LEVEL: INFO
Outputs:
FunctionArn:
Value: !GetAtt DurableFunction.Arn
AliasArn:
Value: !Ref DurableFunction.AliasDeploy:
sam build
sam deploy --guidedDurable Invokes
For functions that invoke other durable functions:
CloudFormation:
DurableFunctionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: lambda.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
Policies:
- PolicyName: InvokeOtherFunctions
PolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Action:
- lambda:InvokeFunction
Resource:
- !GetAtt TargetFunction.Arn
- !Sub '${TargetFunction.Arn}:*' # For versions/aliasesCDK:
const targetFunction = new lambda.Function(this, 'TargetFunction', {
// ... configuration
});
const orchestratorFunction = new lambda.Function(this, 'OrchestratorFunction', {
// ... configuration with durableConfig
});
// Grant invoke permission
targetFunction.grantInvoke(orchestratorFunction);External Callbacks
For external systems to send callbacks:
IAM Policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"lambda:SendDurableExecutionCallbackSuccess",
"lambda:SendDurableExecutionCallbackFailure",
"lambda:SendDurableExecutionCallbackHeartbeat"
],
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:myDurableFunction:*"
}
]
}Environment Configuration
Development:
DurableFunction:
Type: AWS::Lambda::Function
Properties:
DurableConfig:
ExecutionTimeout: 900 # 15 minutes
RetentionPeriodInDays: 1 # Short retention
Environment:
Variables:
LOG_LEVEL: DEBUG # Use INFO or higher in non-dev — DEBUG may expose step results and execution state
ENVIRONMENT: developmentProduction:
DurableFunction:
Type: AWS::Lambda::Function
Properties:
DurableConfig:
ExecutionTimeout: 86400 # 24 hours
RetentionPeriodInDays: 30 # Long retention
Environment:
Variables:
LOG_LEVEL: INFO
ENVIRONMENT: productionMulti-Environment Deployment
CDK with Stages:
const app = new cdk.App();
new DurableFunctionStack(app, 'DurableFunction-Dev', {
env: { account: '123456789012', region: 'us-east-1' },
stage: 'dev',
durableConfig: {
executionTimeout: cdk.Duration.minutes(15),
retentionPeriod: cdk.Duration.days(1)
}
});
new DurableFunctionStack(app, 'DurableFunction-Prod', {
env: { account: '123456789012', region: 'us-east-1' },
stage: 'prod',
durableConfig: {
executionTimeout: cdk.Duration.hours(24),
retentionPeriod: cdk.Duration.days(30)
}
});Invocation Examples
Critical Requirements
⚠️ Important Invocation Rules:
Qualified Function Name Required: You MUST provide a qualified function name with version, alias, or
:$LATESTIdempotency with durable-execution-name: Use this parameter to ensure the same execution name always refers to the same execution
Binary Format: Use
--cli-binary-format raw-in-base64-outto avoid base64 encoding issues
Synchronous Invocation (RequestResponse)
Synchronous invocation waits for the function to complete and returns the result immediately. Suitable for short workflows.
aws lambda invoke \
--function-name 'myDurableFunction:$LATEST' \
--invocation-type RequestResponse \
--durable-execution-name "execution-123" \
--payload '{"userId":"12345","action":"process"}' \
--cli-binary-format raw-in-base64-out \
--output json \
response.json
# View the response
cat response.jsonWhen to use RequestResponse:
Short-running workflows (under 15 minutes total)
When you need the result immediately
Interactive applications requiring synchronous responses
Asynchronous Invocation (Event)
Asynchronous invocation returns immediately with the execution ID. Ideal for long-running workflows.
aws lambda invoke \
--function-name 'myDurableFunction:$LATEST' \
--invocation-type Event \
--durable-execution-name "background-task-456" \
--payload '{"orderId":"ORD-789","amount":99.99}' \
--cli-binary-format raw-in-base64-out \
--output json \
response.json
# Response contains execution ID, not the result
cat response.jsonWhen to use Event:
Long-running workflows (hours, days, or longer)
Background processing tasks
Workflows with wait operations or human-in-the-loop steps
Idempotency with durable-execution-name
The --durable-execution-name parameter ensures that the same execution is never created twice:
# First invocation - creates new execution
aws lambda invoke \
--function-name 'myDurableFunction:$LATEST' \
--invocation-type RequestResponse \
--durable-execution-name "order-processing-ORD-123" \
--payload '{"orderId":"ORD-123"}' \
--cli-binary-format raw-in-base64-out \
response.json
# Second invocation with same execution name - returns existing execution result
aws lambda invoke \
--function-name 'myDurableFunction:$LATEST' \
--invocation-type RequestResponse \
--durable-execution-name "order-processing-ORD-123" \
--payload '{"orderId":"ORD-123"}' \
--cli-binary-format raw-in-base64-out \
response.jsonUsing Specific Function Versions
Durable functions require qualified ARNs (version, alias, or $LATEST):
# ✅ Invoke specific version
aws lambda invoke \
--function-name 'myDurableFunction:1' \
--invocation-type RequestResponse \
--durable-execution-name "versioned-exec-1" \
--payload '{"test":"data"}' \
--cli-binary-format raw-in-base64-out \
response.json
# ✅ Invoke using alias
aws lambda invoke \
--function-name 'myDurableFunction:live' \
--invocation-type RequestResponse \
--durable-execution-name "my-exec-1" \
--payload '{"test":"data"}' \
--cli-binary-format raw-in-base64-out \
response.json
# ❌ Unqualified - will fail!
aws lambda invoke \
--function-name 'myDurableFunction' \
--payload '{"test":"data"}' \
response.json
# Error: Durable execution requires qualified function identifierMonitoring and Observability
CloudWatch Logs:
DurableFunction:
Type: AWS::Lambda::Function
Properties:
# ... other properties
LoggingConfig:
LogFormat: JSON
LogGroup: !Ref DurableFunctionLogGroup
DurableFunctionLogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: /aws/lambda/myDurableFunction
RetentionInDays: 7CloudWatch Alarms:
DurableFunctionErrorAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmName: DurableFunction-Errors
MetricName: Errors
Namespace: AWS/Lambda
Statistic: Sum
Period: 300
EvaluationPeriods: 1
Threshold: 5
ComparisonOperator: GreaterThanThreshold
Dimensions:
- Name: FunctionName
Value: !Ref DurableFunctionBest Practices
Always use qualified ARNs (versions or aliases) for invocation
Set appropriate execution timeouts based on workflow duration
Configure retention periods to balance cost and debugging needs
Use aliases for production deployments
Grant minimal IAM permissions - only what's needed
Enable structured logging (JSON format)
Set up CloudWatch alarms for errors and throttles
Use environment variables for configuration
Deploy to multiple environments (dev, staging, prod)
Version your infrastructure code alongside function code
Common issues
Function Not Durable
Issue: Function executes but doesn't checkpoint.
Solution: Verify DurableConfig is set and role has checkpoint permissions.
Invocation Fails with "Unqualified ARN"
Issue: InvalidParameterValueException: Durable execution requires qualified function identifier
Solution: Use version, alias, or $LATEST:
# ✅ Correct
aws lambda invoke --function-name myFunction:live ...
aws lambda invoke --function-name myFunction:1 ...
# ❌ Wrong
aws lambda invoke --function-name myFunction ...Checkpoint Permission Denied
Issue: AccessDeniedException: User is not authorized to perform: lambda:CheckpointDurableExecution
Solution: Add AWSLambdaBasicDurableExecutionRolePolicy to execution role.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs an MCP server, Needs a command-line tool, Needs Python
Security
What our scanner noticed· Low risk
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- AWS
- Publisher
- AWS (Official)
- Source
- aws/agent-toolkit-for-aws · skills/specialized-skills/serverless-skills/aws-lambda-durable-functions · commit 0a218f8
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- NOTICE (added by AutoGineer from NOTICE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by AWS or AWS.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-lambda-durable-functions.zip