{"id":12011,"library":"serverless-step-functions","title":"Serverless Step Functions Plugin","description":"The `serverless-step-functions` plugin provides deep integration for AWS Step Functions within the Serverless Framework. It allows developers to define, deploy, and manage complex serverless workflows directly within their `serverless.yml` configuration. As of version `3.29.1`, the project maintains a rapid release cadence, frequently pushing out new features and bug fixes, often several times per month. Key differentiators include automatic IAM role generation tailored to state machine definitions, comprehensive event source integrations (such as API Gateway, Scheduled events, and CloudWatch Events), support for advanced features like Blue-Green deployments, pre-deployment validation, CloudWatch Alarms, and X-Ray tracing. It significantly streamlines the orchestration of AWS services by abstracting away much of the underlying CloudFormation complexity required for Step Functions.","status":"active","version":"3.29.1","language":"javascript","source_language":"en","source_url":"https://github.com/serverless-operations/serverless-step-functions","tags":["javascript","serverless"],"install":[{"cmd":"npm install serverless-step-functions","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-step-functions","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-step-functions","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for core framework functionality; plugin requires a compatible Serverless Framework version.","package":"serverless","optional":false}],"imports":[{"note":"The plugin is enabled by listing its name under the `plugins` section of your `serverless.yml`. This is the primary 'import' mechanism for Serverless plugins.","symbol":"serverless-step-functions (plugin declaration)","correct":"plugins:\n  - serverless-step-functions"},{"note":"State machines are defined under the `stepFunctions.stateMachines` property in `serverless.yml`. Incorrect placement or YAML syntax errors are common mistakes.","wrong":"# Incorrect placement, will not be recognized by the plugin:\nstateMachines:\n  myStateMachine:\n    # ...","symbol":"stateMachines (configuration block)","correct":"stepFunctions:\n  stateMachines:\n    myStateMachine:\n      definition:\n        Comment: \"A simple state machine\"\n        StartAt: \"Hello\"\n        States:\n          Hello:\n            Type: Pass\n            End: true"},{"note":"API Gateway events can directly integrate with Step Functions, allowing an HTTP endpoint to start a workflow. Ensure `async: true` and the event is defined *within the state machine's `events` block* to achieve direct asynchronous invocation. Defining it under `functions` creates a Lambda proxy.","wrong":"# Incorrect if you want direct Step Functions integration. This would create a Lambda proxy:\nfunctions:\n  myApiTriggerLambda:\n    handler: handler.myApiTrigger\n    events:\n      - httpApi:\n          path: /my-workflow\n          method: post","symbol":"httpApi event trigger","correct":"stepFunctions:\n  stateMachines:\n    myApiStateMachine:\n      definition:\n        Comment: \"A state machine triggered by API Gateway\"\n        StartAt: \"Hello\"\n        States:\n          Hello:\n            Type: Pass\n            End: true\n      events:\n        - httpApi:\n            path: /my-workflow\n            method: post\n            async: true\n            response:\n              headers:\n                Content-Type: \"'application/json'\"\n              template: \"$input.json('$')\""}],"quickstart":{"code":"# serverless.yml\nservice: my-step-functions-service\n\nframeworkVersion: '3'\n\nplugins:\n  - serverless-step-functions\n\nprovider:\n  name: aws\n  runtime: nodejs20.x # Or any supported runtime\n  region: us-east-1\n  stage: dev\n  httpApi:\n    cors: true\n\nstepFunctions:\n  stateMachines:\n    mySimpleWorkflow:\n      name: my-simple-workflow-${sls:stage}\n      comment: \"A basic workflow that waits and then succeeds\"\n      definition:\n        Comment: \"My Simple Workflow\"\n        StartAt: \"WaitState\"\n        States:\n          WaitState:\n            Type: Wait\n            Seconds: 5\n            Next: \"SucceedState\"\n          SucceedState:\n            Type: Succeed\n      events:\n        - httpApi:\n            path: /start-workflow\n            method: post\n            async: true\n            response:\n              headers:\n                Content-Type: \"'application/json'\"\n              template: \"$input.json('$')\"","lang":"javascript","description":"This `serverless.yml` configuration demonstrates how to define a simple AWS Step Functions state machine with a basic `Wait` and `Succeed` state. It also shows how to trigger this workflow asynchronously via an AWS HTTP API endpoint, configuring the necessary API Gateway integration. This configuration should be placed in your `serverless.yml` file and deployed using `sls deploy`."},"warnings":[{"fix":"Upgrade your Serverless Framework CLI and project configuration to `v3.0.0` or newer. Run `npm install -g serverless@latest` or `npm install serverless@latest` in your project.","message":"Version 3.x of `serverless-step-functions` requires Serverless Framework `v3.0.0` or later. Deployments with older Serverless Framework versions will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your development environment and deployment environment (if running local `sls deploy`) use Node.js version 22 or newer. Consider using `nvm` to manage Node.js versions.","message":"As of recent versions (specifically aligning with Serverless Framework v3.x), the plugin requires Node.js version `22` or higher. Older Node.js versions will result in deployment failures.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Carefully review the CloudFormation generated IAM policies and add any missing permissions under the `iamRoleStatements` section in your `serverless.yml` or the `custom` section of the plugin configuration.","message":"While the plugin aims to auto-generate correct IAM permissions, complex state machine definitions or custom service integrations may still require manual augmentation of IAM roles to prevent permission denied errors during execution.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Avoid deeply nested `Fn::Sub` within Lambda resource references if possible. If necessary, use `Fn::Join` or define the ARN as a separate CloudFormation resource/variable for clarity and to prevent improper parsing.","message":"When using `Fn::Sub` expressions within a Lambda resource ARN for state machine definitions, ensure proper nesting and escaping. Improperly nested `Fn::Sub` can lead to deployment or runtime errors.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always define `apiKeys` as an array of objects, e.g., `- { name: 'my-api-key', value: '...' }` instead of just string names, to ensure compatibility and full feature support.","message":"When defining API Gateway `apiKeys`, ensure you use the object form, especially for more complex configurations. Earlier versions might have had issues with simpler string arrays for `apiKeys`.","severity":"gotcha","affected_versions":">=3.28.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade the Serverless Framework CLI: `npm install -g serverless@latest` and ensure your project's `package.json` specifies `serverless` v3 or greater.","cause":"The installed `serverless-step-functions` plugin requires Serverless Framework `v3.0.0` or higher, but an older version is in use.","error":"Serverless Framework Error: This plugin is not compatible with your version of the Serverless Framework. Please use 'serverless@3.x.x'."},{"fix":"Carefully review your `serverless.yml` for correct YAML syntax, especially indentation, dashes for lists, and proper key-value pairs. Use a YAML linter or IDE support for validation.","cause":"There's a syntax error or incorrect indentation in your `serverless.yml` configuration for the Step Functions plugin.","error":"The CloudFormation template is invalid: Template format error: YAML not well-formed"},{"fix":"Add `states:StartExecution` permission for the specific state machine ARN to the IAM role that triggers the workflow. This might be a `iamRoleStatements` entry in your `serverless.yml` provider section or a custom role defined for the event.","cause":"The IAM role assigned to your API Gateway or other event source does not have the necessary permissions to start the Step Functions state machine execution.","error":"AccessDeniedException: User: arn:aws:iam::... is not authorized to perform: states:StartExecution on resource: arn:aws:states:..."},{"fix":"Verify that any ARNs specified in your state machine definition or event configurations are correct and that the resources they refer to exist and are deployed in the same region/account. Ensure any Serverless variables (e.g., `${self:provider.region}`) are correctly resolved.","cause":"The ARN for a referenced state machine or a related AWS resource in your configuration is incorrectly formatted or points to a non-existent resource.","error":"InvalidArn: The state machine ARN is not valid."}],"ecosystem":"npm"}