AWS Step Functions
Developer Guide

Handling Error Conditions Using a State Machine

This tutorial introduces you to handling error conditions using an AWS Step Functions state machine with a Catch field. In this tutorial, you'll use an AWS Lambda function to respond with conditional logic based on error message type, a method called function error handling. For more information, see Function Error Handling in the AWS 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: Creating an IAM Role for Lambda

Both Lambda and Step Functions can execute code and access AWS resources (for example, data stored in Amazon S3 buckets). To maintain security, you must grant Lambda and Step Functions access to these resources.

In the Getting Started tutorial, this is done automatically for Step Functions: an IAM role is created when you create the state machine. However, Lambda requires you to assign an IAM role when you create a Lambda function in the same way Step Functions requires you to assign an IAM role when you create a state machine.

To create a role for Lambda

  1. Log in to the IAM console and choose Roles, Create New Role.

  2. On the Select Role Type page, select AWS Lambda from the list.


    The role is automatically provided with a trust relationship that allows Lambda to use the role.

  3. On the Attach Policy page, choose Next Step.

  4. On the Set role name and review page, type the Role Name and then choose Create Role.

The role appears in the list of roles in the IAM console.

Step 2: Creating a Lambda Function That Fails

Use a Lambda function to simulate an error condition.


Ensure that your Lambda function is under the same AWS account as your state machine.

To simulate a failing Lambda function

  1. Log in to the Lambda console.

  2. If this is your first Lambda function, choose Get Started Now. Otherwise, choose Create function.

  3. On the Select blueprint page, type step-functions into the filter, and then choose the step-functions-error blueprint.

  4. On the Configure triggers page, choose Next.

  5. On the Configure function page, type FailFunction for the Name.

    The following code is displayed in the Lambda function code pane:

    'use strict'; exports.handler = (event, context, callback) => { function CustomError(message) { = 'CustomError'; this.message = message; } CustomError.prototype = new Error(); const error = new CustomError('This is a custom error!'); callback(error); };

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

  6. In the Lambda function handler and role section, select Choose an existing role from the Role list. Then select the Lambda role that you created earlier from the Existing role list.


    If the IAM role that you created doesn't appear in the list, the role might still need a few minutes to propagate to Lambda.

    You can use the Timeout value in the Advanced settings to specify how long your function can take to execute before failing.

  7. Choose Next, review your function, and then choose Create function.

  8. When your Lambda function is created, note its Amazon Resource Name (ARN), which is displayed in the upper-right corner of the page. For example:


Step 3: Testing the Lambda Function

Test your Lambda function to see it in operation.

To test your Lambda function

  1. On your Lambda function page, choose Test.

    The Input test event dialog box is displayed.

  2. Choose Save and test.

    The results of the test (the simulated error) are displayed at the bottom of the page.

Step 4: Creating a State Machine with a Catch Field

Use the Step Functions console to create a state machine that uses a Task 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.

To create the state machine

  1. Log in to the Step Functions console and choose Get Started.

  2. On the Create a state machine page, choose the Catch Failure blueprint.

  3. In the box under Name your State Machine, type a name, for example CatchStateMachine.


    State machine names must be 1-80 characters in length, must be unique for your account and region, and must not contain any of the following:

    • Whitespace

    • Whitespace characters (? *)

    • Bracket characters (< > { } [ ])

    • Special characters (: ; , \ | ^ ~ $ # % & ` ")

    • Control characters (\\u0000 - \\u001f or \\u007f - \\u009f).

  4. In the Code pane, add the ARN of the Lambda function that you created earlier in the Resource field, for example:

    { "Comment": "A Catch example of the Amazon States Language using an AWS Lambda function", "StartAt": "CreateAccount", "States": { "CreateAccount": { "Type": "Task", "Resource": "arn:aws: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 Retrying After an Error.

  5. Choose Create State Machine.

    The IAM role for your state machine executions dialog box is displayed. Step Functions creates and selects an IAM role automatically.


    If you delete the IAM role that Step Functions creates, Step Functions can't recreate it later. Similarly, if you modify the role (for example, by removing Step Functions from the principals in the IAM policy), Step Functions can't restore its original settings later. For more information about creating an IAM role manually, see Creating IAM Roles for Use with AWS Step Functions.

  6. Choose OK.

Step 5: Starting a New Execution

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

To start a new execution

  1. On the CatchStateMachine page, choose New execution.

    The New execution page is displayed.

  2. (Optional) To help identify your execution, you can enter an ID for it. To specify the ID, use the Enter your execution id here text box. If you don't enter an ID, Step Functions generates a unique ID automatically.

  3. Choose Start Execution.

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

  4. In the Execution Details section, choose the Info tab to view the Execution Status and the Started and Closed timestamps.

  5. To view the results of your execution, choose the Output tab.