{"id":9529,"library":"aws-cdk-aws-stepfunctions","title":"AWS CDK AWS Step Functions","description":"The `aws-cdk-aws-stepfunctions` library is the AWS Cloud Development Kit (CDK) Construct Library for defining AWS Step Functions state machines in Python. It allows developers to programmatically create and manage Step Functions workflows, including states, tasks, and error handling. As of version `1.204.0`, this package is part of the AWS CDK v1 ecosystem, which typically sees frequent updates aligning with broader CDK releases.","status":"active","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","stepfunctions","iac","cloud","workflow","serverless"],"install":[{"cmd":"pip install aws-cdk.aws-stepfunctions","lang":"bash","label":"Install library"},{"cmd":"pip install aws-cdk.core","lang":"bash","label":"Install core CDK (if not already)"}],"dependencies":[{"reason":"Provides the core CDK constructs like App, Stack, and Duration.","package":"aws-cdk.core","optional":false},{"reason":"Requires Python 3.7 or higher.","package":"python","optional":false}],"imports":[{"note":"Commonly aliased as 'cdk' for brevity and consistency in CDK v1.","wrong":"import aws_cdk.core","symbol":"core","correct":"from aws_cdk import core as cdk"},{"note":"Aliasing as 'sfn' is standard practice. Avoid wildcard imports for clarity.","wrong":"from aws_cdk.aws_stepfunctions import *","symbol":"aws_stepfunctions","correct":"from aws_cdk import aws_stepfunctions as sfn"}],"quickstart":{"code":"import os\nfrom aws_cdk import core as cdk\nfrom aws_cdk import aws_stepfunctions as sfn\n\n# Define your CDK Stack\nclass MyStepFunctionStack(cdk.Stack):\n    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # Define a simple Pass state\n        pass_state = sfn.Pass(self, \"MyPassState\",\n            state_json={\n                \"Comment\": \"A simple pass state for demonstration\",\n                \"InputPath\": \"$\",\n                \"OutputPath\": \"$\",\n                \"Result\": {\"status\": \"SUCCESS\", \"source\": \"CDK\"},\n                \"End\": True\n            }\n        )\n\n        # Define a State Machine using the Pass state\n        sfn.StateMachine(self, \"MyCDKStateMachine\",\n            definition=pass_state,\n            state_machine_name=\"MyCDKPassStateMachine\", # Optional: explicit name\n            timeout=cdk.Duration.minutes(5) # Optional: default timeout\n        )\n\n# Instantiate the CDK App and Stack\napp = cdk.App()\nMyStepFunctionStack(app, \"MyStepFunctionStack\")\napp.synth()\n","lang":"python","description":"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."},"warnings":[{"fix":"Choose 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).","message":"This 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.","severity":"breaking","affected_versions":"All versions of aws-cdk-aws-stepfunctions (v1) and aws-cdk-lib (v2)"},{"fix":"Ensure 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.","message":"AWS 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"State 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure 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.","message":"CDK'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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Activate your Python virtual environment and run `pip install aws-cdk.aws-stepfunctions aws-cdk.core`.","cause":"The Python package for AWS Step Functions constructs is not installed or the virtual environment is not active.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_stepfunctions'"},{"fix":"Navigate to the root directory of your CDK project where `app.py` resides before running `cdk synth` or `cdk deploy`.","cause":"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`).","error":"jsii.errors.JavaScriptError: There are no `app.py`, `app.ts` or `main.py` files in ..."},{"fix":"Attach 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.","cause":"The AWS IAM user or role attempting to deploy the CDK stack lacks the necessary permissions to create or update Step Functions resources.","error":"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:..."}]}