Registry /
aws / aws-cdk-aws-stepfunctions
Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 80.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.1s · import 0.000s · 39MB
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
core
✓ from aws_cdk import core as cdk
✗ import aws_cdk.core
Commonly aliased as 'cdk' for brevity and consistency in CDK v1.
aws_stepfunctions
✓ from aws_cdk import aws_stepfunctions as sfn
✗ from aws_cdk.aws_stepfunctions import *
Aliasing as 'sfn' is standard practice. Avoid wildcard imports for clarity.
This quickstart demonstrates how to define a basic AWS Step Functions State Machine using a simple 'Pass' state. It initializes a CDK application, creates a stack, defines the Pass state with a basic JSON definition, and then constructs a `StateMachine` resource. The `app.synth()` call generates the AWS CloudFormation template. To deploy, ensure AWS credentials are configured and run `cdk deploy MyStepFunctionStack` in your terminal.
import os
from aws_cdk import core as cdk
from aws_cdk import aws_stepfunctions as sfn
# Define your CDK Stack
class MyStepFunctionStack(cdk.Stack):
def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Define a simple Pass state
pass_state = sfn.Pass(self, "MyPassState",
state_json={
"Comment": "A simple pass state for demonstration",
"InputPath": "$",
"OutputPath": "$",
"Result": {"status": "SUCCESS", "source": "CDK"},
"End": True
}
)
# Define a State Machine using the Pass state
sfn.StateMachine(self, "MyCDKStateMachine",
definition=pass_state,
state_machine_name="MyCDKPassStateMachine", # Optional: explicit name
timeout=cdk.Duration.minutes(5) # Optional: default timeout
)
# Instantiate the CDK App and Stack
app = cdk.App()
MyStepFunctionStack(app, "MyStepFunctionStack")
app.synth()
Debug
Known issues
breakingThis library (`aws-cdk-aws-stepfunctions`) is part of AWS CDK v1. AWS CDK v2 uses a consolidated `aws-cdk-lib` package. Do not mix v1 and v2 packages in the same project, as it leads to dependency conflicts and runtime errors.fixChoose either CDK v1 or CDK v2 for your project. If using v2, install `aws-cdk-lib` and import Step Functions as `from aws_cdk import aws_stepfunctions as sfn` (without `lib` in the import path).
affects: All versions of aws-cdk-aws-stepfunctions (v1) and aws-cdk-lib (v2)
gotchaAWS Step Functions require appropriate IAM permissions for the state machine to execute and for its tasks (e.g., Lambda, ECS) to interact with other AWS services. Insufficient permissions will result in execution failures that are often hard to debug.fixEnsure the `role` property of your `sfn.StateMachine` and any `sfn.tasks` or `sfn.LambdaInvoke` constructs have roles with the necessary permissions. Use `aws_iam.Role` and `aws_iam.PolicyStatement` to define and attach granular permissions.
affects: All versions
gotchaState machine definitions can quickly grow in complexity and size, potentially hitting AWS service limits (e.g., 262144 characters for definition JSON). While CDK helps abstract this, highly complex workflows can still exceed limits.fixFor very large state machine definitions, consider breaking them into smaller, nested state machines or using data flow optimization techniques. Review Step Functions service quotas before designing complex workflows.
affects: All versions
gotchaCDK's `cdk synth` command generates CloudFormation, but `cdk deploy` requires AWS credentials configured in your environment (e.g., via AWS CLI, environment variables, or IAM roles for EC2/ECS).fixConfigure your AWS credentials and default region before running `cdk deploy`. Use `aws configure` or set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_cdk.aws_stepfunctions'
The Python package for AWS Step Functions constructs is not installed or the virtual environment is not active.
fixActivate your Python virtual environment and run `pip install aws-cdk.aws-stepfunctions aws-cdk.core`.
jsii.errors.JavaScriptError: There are no `app.py`, `app.ts` or `main.py` files in ...
The `cdk synth` or `cdk deploy` command was executed in a directory that does not contain the CDK application entry point (e.g., `app.py`).
fixNavigate to the root directory of your CDK project where `app.py` resides before running `cdk synth` or `cdk deploy`.
ClientError: An error occurred (AccessDeniedException) when calling the CreateStateMachine operation: User: arn:aws:iam::xxxxxxxxxxxx:user/your-user is not authorized to perform: states:CreateStateMachine on resource: arn:aws:states:...
The AWS IAM user or role attempting to deploy the CDK stack lacks the necessary permissions to create or update Step Functions resources.
fixAttach an IAM policy with `states:CreateStateMachine`, `states:UpdateStateMachine`, and `states:DeleteStateMachine` permissions (and potentially permissions for related resources like `iam:PassRole`) to the user or role deploying the stack.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredProvides the core CDK constructs like App, Stack, and Duration.
pythonrequiredRequires Python 3.7 or higher.