Serverless Step Functions Plugin

3.29.1 · active · verified Sun Apr 19

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.

Common errors

```
Serverless Framework Error: This plugin is not compatible with your version of the Serverless Framework. Please use 'serverless@3.x.x'.
```
cause The installed `serverless-step-functions` plugin requires Serverless Framework `v3.0.0` or higher, but an older version is in use.

fix Upgrade the Serverless Framework CLI: `npm install -g serverless@latest` and ensure your project's `package.json` specifies `serverless` v3 or greater.
```
The CloudFormation template is invalid: Template format error: YAML not well-formed
```
cause There's a syntax error or incorrect indentation in your `serverless.yml` configuration for the Step Functions plugin.

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.
```
AccessDeniedException: User: arn:aws:iam::... is not authorized to perform: states:StartExecution on resource: arn:aws:states:...
```
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.

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.
```
InvalidArn: The state machine ARN is not valid.
```
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.

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.

Warnings

breaking Version 3.x of `serverless-step-functions` requires Serverless Framework `v3.0.0` or later. Deployments with older Serverless Framework versions will fail.
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.
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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`.
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.

Install

npm install serverless-step-functions npm
yarn add serverless-step-functions yarn
pnpm add serverless-step-functions pnpm

Imports

serverless-step-functions (plugin declaration)
```
plugins:
  - serverless-step-functions
```
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.

stateMachines (configuration block)

wrong:

# Incorrect placement, will not be recognized by the plugin:
stateMachines:
  myStateMachine:
    # ...

correct:

stepFunctions:
  stateMachines:
    myStateMachine:
      definition:
        Comment: "A simple state machine"
        StartAt: "Hello"
        States:
          Hello:
            Type: Pass
            End: true

State machines are defined under the `stepFunctions.stateMachines` property in `serverless.yml`. Incorrect placement or YAML syntax errors are common mistakes.

httpApi event trigger

wrong:

# Incorrect if you want direct Step Functions integration. This would create a Lambda proxy:
functions:
  myApiTriggerLambda:
    handler: handler.myApiTrigger
    events:
      - httpApi:
          path: /my-workflow
          method: post

correct:

stepFunctions:
  stateMachines:
    myApiStateMachine:
      definition:
        Comment: "A state machine triggered by API Gateway"
        StartAt: "Hello"
        States:
          Hello:
            Type: Pass
            End: true
      events:
        - httpApi:
            path: /my-workflow
            method: post
            async: true
            response:
              headers:
                Content-Type: "'application/json'"
              template: "$input.json('$')"

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.

Quickstart

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`.

# serverless.yml
service: my-step-functions-service

frameworkVersion: '3'

plugins:
  - serverless-step-functions

provider:
  name: aws
  runtime: nodejs20.x # Or any supported runtime
  region: us-east-1
  stage: dev
  httpApi:
    cors: true

stepFunctions:
  stateMachines:
    mySimpleWorkflow:
      name: my-simple-workflow-${sls:stage}
      comment: "A basic workflow that waits and then succeeds"
      definition:
        Comment: "My Simple Workflow"
        StartAt: "WaitState"
        States:
          WaitState:
            Type: Wait
            Seconds: 5
            Next: "SucceedState"
          SucceedState:
            Type: Succeed
      events:
        - httpApi:
            path: /start-workflow
            method: post
            async: true
            response:
              headers:
                Content-Type: "'application/json'"
              template: "$input.json('$')"

view raw JSON →