---
name: step-functions
description: AWS Step Functions workflow orchestration with state machines. Use when designing workflows, implementing error handling, configuring parallel execution, integrating with AWS services, or debugging executions.
last_updated: "2026-01-07"
doc_source: https://docs.aws.amazon.com/step-functions/latest/dg/
---

# AWS Step Functions

AWS Step Functions is a serverless orchestration service that lets you build and run workflows using state machines. Coordinate multiple AWS services into business-critical applications.

## Table of Contents

- [Core Concepts](#core-concepts)
- [Common Patterns](#common-patterns)
- [CLI Reference](#cli-reference)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)
- [References](#references)

## Core Concepts

### Workflow Types

| Type | Description | Pricing |
|------|-------------|---------|
| **Standard** | Long-running, durable, exactly-once | Per state transition |
| **Express** | High-volume, short-duration | Per execution (time + memory) |

### State Types

| State | Description |
|-------|-------------|
| **Task** | Execute work (Lambda, API call) |
| **Choice** | Conditional branching |
| **Parallel** | Execute branches concurrently |
| **Map** | Iterate over array |
| **Wait** | Delay execution |
| **Pass** | Pass input to output |
| **Succeed** | End successfully |
| **Fail** | End with failure |

### Amazon States Language (ASL)

JSON-based language for defining state machines.

## Common Patterns

### Simple Lambda Workflow

```json
{
  "Comment": "Process order workflow",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:ValidateOrder",
      "Next": "ProcessPayment"
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:ProcessPayment",
      "Next": "FulfillOrder"
    },
    "FulfillOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FulfillOrder",
      "End": true
    }
  }
}
```

### Create State Machine

**AWS CLI:**

```bash
aws stepfunctions create-state-machine \
  --name OrderWorkflow \
  --definition file://workflow.json \
  --role-arn arn:aws:iam::123456789012:role/StepFunctionsRole \
  --type STANDARD
```

**boto3:**

```python
import boto3
import json

sfn = boto3.client('stepfunctions')

definition = {
    "Comment": "Order workflow",
    "StartAt": "ProcessOrder",
    "States": {
        "ProcessOrder": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:...",
            "End": True
        }
    }
}

response = sfn.create_state_machine(
    name='OrderWorkflow',
    definition=json.dumps(definition),
    roleArn='arn:aws:iam::123456789012:role/StepFunctionsRole',
    type='STANDARD'
)
```

### Start Execution

```python
import boto3
import json

sfn = boto3.client('stepfunctions')

response = sfn.start_execution(
    stateMachineArn='arn:aws:states:us-east-1:123456789012:stateMachine:OrderWorkflow',
    name='order-12345',
    input=json.dumps({
        'order_id': '12345',
        'customer_id': 'cust-789',
        'items': [{'product_id': 'prod-1', 'quantity': 2}]
    })
)

execution_arn = response['executionArn']
```

### Choice State (Conditional Logic)

```json
{
  "StartAt": "CheckOrderValue",
  "States": {
    "CheckOrderValue": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.total",
          "NumericGreaterThan": 1000,
          "Next": "HighValueOrder"
        },
        {
          "Variable": "$.priority",
          "StringEquals": "rush",
          "Next": "RushOrder"
        }
      ],
      "Default": "StandardOrder"
    },
    "HighValueOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessHighValue",
      "End": true
    },
    "RushOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessRush",
      "End": true
    },
    "StandardOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessStandard",
      "End": true
    }
  }
}
```

### Parallel Execution

```json
{
  "StartAt": "ProcessInParallel",
  "States": {
    "ProcessInParallel": {
      "Type": "Parallel",
      "Branches": [
        {
          "StartAt": "UpdateInventory",
          "States": {
            "UpdateInventory": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:UpdateInventory",
              "End": true
            }
          }
        },
        {
          "StartAt": "SendNotification",
          "States": {
            "SendNotification": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:SendNotification",
              "End": true
            }
          }
        },
        {
          "StartAt": "UpdateAnalytics",
          "States": {
            "UpdateAnalytics": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:UpdateAnalytics",
              "End": true
            }
          }
        }
      ],
      "Next": "Complete"
    },
    "Complete": {
      "Type": "Succeed"
    }
  }
}
```

### Map State (Iteration)

```json
{
  "StartAt": "ProcessItems",
  "States": {
    "ProcessItems": {
      "Type": "Map",
      "ItemsPath": "$.items",
      "MaxConcurrency": 10,
      "Iterator": {
        "StartAt": "ProcessItem",
        "States": {
          "ProcessItem": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:...:function:ProcessItem",
            "End": true
          }
        }
      },
      "ResultPath": "$.processedItems",
      "End": true
    }
  }
}
```

### Error Handling

```json
{
  "StartAt": "ProcessWithRetry",
  "States": {
    "ProcessWithRetry": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:Process",
      "Retry": [
        {
          "ErrorEquals": ["Lambda.ServiceException", "Lambda.TooManyRequestsException"],
          "IntervalSeconds": 2,
          "MaxAttempts": 6,
          "BackoffRate": 2
        },
        {
          "ErrorEquals": ["States.Timeout"],
          "IntervalSeconds": 5,
          "MaxAttempts": 3,
          "BackoffRate": 1.5
        }
      ],
      "Catch": [
        {
          "ErrorEquals": ["CustomError"],
          "ResultPath": "$.error",
          "Next": "HandleCustomError"
        },
        {
          "ErrorEquals": ["States.ALL"],
          "ResultPath": "$.error",
          "Next": "HandleAllErrors"
        }
      ],
      "End": true
    },
    "HandleCustomError": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:HandleCustom",
      "End": true
    },
    "HandleAllErrors": {
      "Type": "Fail",
      "Error": "ProcessingFailed",
      "Cause": "An error occurred during processing"
    }
  }
}
```

## CLI Reference

### State Machine Management

| Command | Description |
|---------|-------------|
| `aws stepfunctions create-state-machine` | Create state machine |
| `aws stepfunctions update-state-machine` | Update definition |
| `aws stepfunctions delete-state-machine` | Delete state machine |
| `aws stepfunctions list-state-machines` | List state machines |
| `aws stepfunctions describe-state-machine` | Get details |

### Executions

| Command | Description |
|---------|-------------|
| `aws stepfunctions start-execution` | Start execution |
| `aws stepfunctions stop-execution` | Stop execution |
| `aws stepfunctions describe-execution` | Get execution details |
| `aws stepfunctions list-executions` | List executions |
| `aws stepfunctions get-execution-history` | Get execution history |

## Best Practices

### Design

- **Keep states focused** — one purpose per state
- **Use meaningful state names**
- **Implement comprehensive error handling**
- **Use Parallel for independent tasks**
- **Use Map for batch processing**

### Performance

- **Use Express workflows** for high-volume, short tasks
- **Set appropriate timeouts**
- **Limit Map concurrency** to avoid throttling
- **Use SDK integrations** when possible (avoid Lambda wrapper)

### Reliability

- **Retry transient errors**
- **Catch and handle specific errors**
- **Use idempotent operations**
- **Enable X-Ray tracing**

### Cost Optimization

- **Use Express for short workflows** (< 5 minutes)
- **Combine related operations** to reduce transitions
- **Use Wait states** instead of Lambda delays

## Troubleshooting

### Execution Failed

```bash
# Get execution history
aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:us-east-1:123456789012:execution:MyWorkflow:exec-123 \
  --query 'events[?type==`TaskFailed` || type==`ExecutionFailed`]'
```

### Lambda Timeout

**Causes:**
- Lambda running too long
- Task timeout too short

**Fix:**

```json
{
  "Type": "Task",
  "Resource": "arn:aws:lambda:...",
  "TimeoutSeconds": 300,
  "HeartbeatSeconds": 60
}
```

### State Stuck

**Check:**
- Task state waiting for callback
- Wait state not yet elapsed
- Activity worker not responding

### Invalid State Machine

```bash
# Validate definition
aws stepfunctions validate-state-machine-definition \
  --definition file://workflow.json
```

## References

- [Step Functions Developer Guide](https://docs.aws.amazon.com/step-functions/latest/dg/)
- [Step Functions API Reference](https://docs.aws.amazon.com/step-functions/latest/apireference/)
- [Step Functions CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/stepfunctions/)
- [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html)

# Step Functions Workflow Patterns

Advanced workflow patterns and SDK integrations.

## SDK Integrations

### Lambda (Optimized)

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::lambda:invoke",
  "Parameters": {
    "FunctionName": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
    "Payload.$": "$"
  },
  "OutputPath": "$.Payload",
  "End": true
}
```

### DynamoDB GetItem

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::dynamodb:getItem",
  "Parameters": {
    "TableName": "Orders",
    "Key": {
      "order_id": {"S.$": "$.order_id"}
    }
  },
  "ResultPath": "$.order",
  "Next": "ProcessOrder"
}
```

### DynamoDB PutItem

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::dynamodb:putItem",
  "Parameters": {
    "TableName": "Orders",
    "Item": {
      "order_id": {"S.$": "$.order_id"},
      "status": {"S": "processed"},
      "processed_at": {"S.$": "$$.State.EnteredTime"}
    }
  },
  "End": true
}
```

### SQS SendMessage

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::sqs:sendMessage",
  "Parameters": {
    "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue",
    "MessageBody.$": "States.JsonToString($)"
  },
  "End": true
}
```

### SNS Publish

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::sns:publish",
  "Parameters": {
    "TopicArn": "arn:aws:sns:us-east-1:123456789012:my-topic",
    "Message.$": "$.message",
    "Subject": "Order Notification"
  },
  "End": true
}
```

### Step Functions (Nested)

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::states:startExecution.sync:2",
  "Parameters": {
    "StateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:ChildWorkflow",
    "Input.$": "$"
  },
  "End": true
}
```

### ECS RunTask

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::ecs:runTask.sync",
  "Parameters": {
    "LaunchType": "FARGATE",
    "Cluster": "arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster",
    "TaskDefinition": "my-task:1",
    "NetworkConfiguration": {
      "AwsvpcConfiguration": {
        "Subnets": ["subnet-12345678"],
        "SecurityGroups": ["sg-12345678"],
        "AssignPublicIp": "ENABLED"
      }
    },
    "Overrides": {
      "ContainerOverrides": [{
        "Name": "my-container",
        "Environment": [
          {"Name": "INPUT", "Value.$": "States.JsonToString($)"}
        ]
      }]
    }
  },
  "End": true
}
```

### EventBridge PutEvents

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::events:putEvents",
  "Parameters": {
    "Entries": [
      {
        "Source": "my-app.orders",
        "DetailType": "Order Completed",
        "Detail.$": "States.JsonToString($)",
        "EventBusName": "my-event-bus"
      }
    ]
  },
  "End": true
}
```

## Callback Pattern

### Wait for External Process

```json
{
  "Type": "Task",
  "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
  "Parameters": {
    "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/approval-queue",
    "MessageBody": {
      "token.$": "$$.Task.Token",
      "order_id.$": "$.order_id",
      "action": "approve_order"
    }
  },
  "TimeoutSeconds": 86400,
  "Next": "ProcessApproval"
}
```

### Complete Callback (from external process)

```python
import boto3

sfn = boto3.client('stepfunctions')

# On success
sfn.send_task_success(
    taskToken=task_token,
    output='{"approved": true, "approver": "user@example.com"}'
)

# On failure
sfn.send_task_failure(
    taskToken=task_token,
    error='RejectedError',
    cause='Order rejected by approver'
)

# Heartbeat (for long-running tasks)
sfn.send_task_heartbeat(taskToken=task_token)
```

## Distributed Map

### Process Large Dataset

```json
{
  "Type": "Map",
  "ItemProcessor": {
    "ProcessorConfig": {
      "Mode": "DISTRIBUTED",
      "ExecutionType": "STANDARD"
    },
    "StartAt": "ProcessItem",
    "States": {
      "ProcessItem": {
        "Type": "Task",
        "Resource": "arn:aws:lambda:...:function:ProcessItem",
        "End": true
      }
    }
  },
  "ItemReader": {
    "Resource": "arn:aws:states:::s3:getObject",
    "ReaderConfig": {
      "InputType": "JSON"
    },
    "Parameters": {
      "Bucket": "my-bucket",
      "Key": "input/data.json"
    }
  },
  "ResultWriter": {
    "Resource": "arn:aws:states:::s3:putObject",
    "Parameters": {
      "Bucket": "my-bucket",
      "Prefix": "output"
    }
  },
  "MaxConcurrency": 1000,
  "End": true
}
```

## Intrinsic Functions

### String Operations

```json
{
  "Type": "Pass",
  "Parameters": {
    "concatenated.$": "States.Format('Order {} for customer {}', $.order_id, $.customer_id)",
    "split.$": "States.StringSplit($.tags, ',')",
    "uuid.$": "States.UUID()"
  }
}
```

### Array Operations

```json
{
  "Type": "Pass",
  "Parameters": {
    "arrayLength.$": "States.ArrayLength($.items)",
    "firstItem.$": "States.ArrayGetItem($.items, 0)",
    "range.$": "States.ArrayRange(1, 10, 2)",
    "partition.$": "States.ArrayPartition($.items, 10)",
    "unique.$": "States.ArrayUnique($.items)"
  }
}
```

### JSON Operations

```json
{
  "Type": "Pass",
  "Parameters": {
    "stringified.$": "States.JsonToString($.data)",
    "parsed.$": "States.StringToJson($.jsonString)",
    "merged.$": "States.JsonMerge($.base, $.override, false)"
  }
}
```

### Math Operations

```json
{
  "Type": "Pass",
  "Parameters": {
    "sum.$": "States.MathAdd($.a, $.b)",
    "random.$": "States.MathRandom(1, 100)"
  }
}
```

## Common Patterns

### Saga Pattern (Compensation)

```json
{
  "StartAt": "ReserveInventory",
  "States": {
    "ReserveInventory": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ReserveInventory",
      "Catch": [{
        "ErrorEquals": ["States.ALL"],
        "Next": "FailOrder"
      }],
      "Next": "ProcessPayment"
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessPayment",
      "Catch": [{
        "ErrorEquals": ["States.ALL"],
        "ResultPath": "$.error",
        "Next": "ReleaseInventory"
      }],
      "Next": "ShipOrder"
    },
    "ShipOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ShipOrder",
      "Catch": [{
        "ErrorEquals": ["States.ALL"],
        "ResultPath": "$.error",
        "Next": "RefundPayment"
      }],
      "End": true
    },
    "ReleaseInventory": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ReleaseInventory",
      "Next": "FailOrder"
    },
    "RefundPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:RefundPayment",
      "Next": "ReleaseInventory"
    },
    "FailOrder": {
      "Type": "Fail",
      "Error": "OrderFailed",
      "Cause": "Order processing failed"
    }
  }
}
```

### Human Approval

```json
{
  "StartAt": "SubmitRequest",
  "States": {
    "SubmitRequest": {
      "Type": "Task",
      "Resource": "arn:aws:states:::lambda:invoke",
      "Parameters": {
        "FunctionName": "CreateApprovalRequest",
        "Payload.$": "$"
      },
      "Next": "WaitForApproval"
    },
    "WaitForApproval": {
      "Type": "Task",
      "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken",
      "Parameters": {
        "FunctionName": "SendApprovalEmail",
        "Payload": {
          "token.$": "$$.Task.Token",
          "request.$": "$"
        }
      },
      "TimeoutSeconds": 604800,
      "Catch": [{
        "ErrorEquals": ["States.Timeout"],
        "Next": "RequestExpired"
      }],
      "Next": "CheckApproval"
    },
    "CheckApproval": {
      "Type": "Choice",
      "Choices": [{
        "Variable": "$.approved",
        "BooleanEquals": true,
        "Next": "ProcessApproved"
      }],
      "Default": "ProcessRejected"
    },
    "ProcessApproved": {
      "Type": "Succeed"
    },
    "ProcessRejected": {
      "Type": "Fail",
      "Error": "Rejected"
    },
    "RequestExpired": {
      "Type": "Fail",
      "Error": "Expired"
    }
  }
}
```

### Polling Pattern

```json
{
  "StartAt": "SubmitJob",
  "States": {
    "SubmitJob": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:SubmitJob",
      "Next": "Wait"
    },
    "Wait": {
      "Type": "Wait",
      "Seconds": 30,
      "Next": "CheckStatus"
    },
    "CheckStatus": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:CheckJobStatus",
      "Next": "IsComplete"
    },
    "IsComplete": {
      "Type": "Choice",
      "Choices": [{
        "Variable": "$.status",
        "StringEquals": "COMPLETED",
        "Next": "GetResults"
      }, {
        "Variable": "$.status",
        "StringEquals": "FAILED",
        "Next": "JobFailed"
      }],
      "Default": "Wait"
    },
    "GetResults": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:GetResults",
      "End": true
    },
    "JobFailed": {
      "Type": "Fail"
    }
  }
}
```