Handling error conditions using a Step Functions state machine - Amazon Step Functions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Handling error conditions using a Step Functions state machine

In this tutorial, you create an Amazon Step Functions state machine with a Catch field. The Catch field uses an Amazon Lambda function to respond with conditional logic based on error message type. This is a technique called function error handling.

For more information, see Amazon Lambda function errors in Node.js in the Amazon Lambda Developer Guide.


You can also create state machines that Retry on timeouts or those that use Catch to transition to a specific state when an error or timeout occurs. For examples of these error handling techniques, see Examples Using Retry and Using Catch.

Step 1: Create a Lambda function that fails

Use a Lambda function to simulate an error condition.


Ensure that your Lambda function is under the same Amazon account and Amazon Region as your state machine.

  1. Open the Amazon Lambda console at https://console.amazonaws.cn/lambda/.

  2. Choose Create function.

  3. Choose Use a blueprint, enter step-functions into the search box, and then choose the Throw a custom error blueprint.

  4. For Function name, enter FailFunction.

  5. For Role, keep the default selection (Create a new role with basic Lambda permissions).

  6. The following code is displayed in the Lambda function code pane.

    exports.handler = async (event, context) => { function CustomError(message) { this.name = 'CustomError'; this.message = message; } CustomError.prototype = new Error(); throw new CustomError('This is a custom error!'); };

    The context object returns the error message This is a custom error!.

  7. Choose Create function.

  8. After your Lambda function is created, copy the function's Amazon Resource Name (ARN) displayed in the upper-right corner of the page. To copy the ARN, click 
                                copy Amazon Resource Name
                            . The following is an example ARN:

  9. Choose Deploy.

Step 2: Test the Lambda function

Test your Lambda function to see it in operation.

  1. On the FailFunction page, choose the Test tab, and then choose Test. You don't need to create a test event.

  2. To review the test results (the simulated error), under Execution result, expand Details.

Step 3: Create a state machine with a catch field

Use the Step Functions console to create a state machine that uses a Task state with a Catch field. Add a reference to your Lambda function in the Task state. The Lambda function is invoked and fails during execution. Step Functions retries the function twice using exponential backoff between retries.

  1. Open the Step Functions console and choose Create state machine.

  2. On the Choose authoring method page, choose Write your workflow in code.

  3. For Type, keep the default selection (Standard).

  4. In the Definition pane, paste the following code, but replace the ARN of the Lambda function that you created earlier in the Resource field.

    { "Comment": "A Catch example of the Amazon States Language using an Amazon Lambda function", "StartAt": "CreateAccount", "States": { "CreateAccount": { "Type": "Task", "Resource": "arn:aws-cn:lambda:us-east-1:123456789012:function:FailFunction", "Catch": [ { "ErrorEquals": ["CustomError"], "Next": "CustomErrorFallback" }, { "ErrorEquals": ["States.TaskFailed"], "Next": "ReservedTypeFallback" }, { "ErrorEquals": ["States.ALL"], "Next": "CatchAllFallback" } ], "End": true }, "CustomErrorFallback": { "Type": "Pass", "Result": "This is a fallback from a custom Lambda function exception", "End": true }, "ReservedTypeFallback": { "Type": "Pass", "Result": "This is a fallback from a reserved error code", "End": true }, "CatchAllFallback": { "Type": "Pass", "Result": "This is a fallback from any error code", "End": true } } }

    This is a description of your state machine using the Amazon States Language. It defines a single Task state named CreateAccount. For more information, see State Machine Structure.

    For more information about the syntax of the Retry field, see Examples using Retry and using Catch.


    Unhandled errors in Lambda are reported as Lambda.Unknown in the error output. These include out-of-memory errors and function timeouts. You can match on Lambda.Unknown, States.ALL, or States.TaskFailed to handle these errors. When Lambda hits the maximum number of invocations, the error is Lambda.TooManyRequestsException. For more information about Lambda function errors, see Error handling and automatic retries in the Amazon Lambda Developer Guide.

  5. Use the graph in the Visual Workflow pane to check that your Amazon States Language code describes your state machine correctly.

    If you don't see the graph, choose 
    in the Visual Workflow pane.

  6. Choose Next.

  7. Enter a Name for your state machine, such as Catchfailure.

  8. In Permissions, choose Create new role.

  9. Choose Create state machine.

Step 4: Start a new execution

After you create your state machine, you can start an execution.

  1. On the Catchfailure page, choose Start execution. The Start execution dialog box is displayed.

  2. (Optional) To identify your execution, you can specify a name for it in the Name box. By default, Step Functions generates a unique execution name automatically.


    Step Functions allows you to create state machine, execution, and activity names that contain non-ASCII characters. These non-ASCII names don't work with Amazon CloudWatch. To ensure that you can track CloudWatch metrics, choose a name that uses only ASCII characters.

  3. Choose Start Execution. A new execution of your state machine starts, and a new page showing your running execution is displayed.

  4. Go to the Execution output tab to view the output of your workflow.

                            Execution output
  5. To view your custom error message, select CreateAccount in the Graph view pane, and then review the Input and output tab.

                            Error output

    You can preserve the state input with the error by using ResultPath. See Use ResultPath to Include Both Error and Input in a Catch.