Handling error conditions using a Step Functions state machine - Amazon Step Functions
Step 1: Create a Lambda function that failsStep 2: Test the Lambda functionStep 3: Create a state machine with a Catch fieldStep 4: Run the state machine
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 Fallback states 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.

Note

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.

Important

Ensure that your Lambda function is under the same Amazon account and Amazon Web Services 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. The following is an example ARN:

    arn:aws-cn:lambda:region:123456789012:function:FailFunction

  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 workflow state state with a Catch field. Add a reference to your Lambda function in the Task state. The state machine invokes the Lambda function, which 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. In the Choose a template dialog box, select Blank.

  3. Choose Select to open Workflow Studio in Design mode.

  4. Choose Code to open the code editor. In the code editor, you write and edit the Amazon States Language (ASL) definition of your workflows.

  5. 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:region: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 State machine examples using Retry and using Catch.

    Note

    Unhandled errors in Lambda runtimes were historically reported only as Lambda.Unknown. In newer runtimes, timeouts are reported as Sandbox.Timedout in the error output.

    When Lambda exceeds the maximum number of invocations, the reported error will be Lambda.TooManyRequestsException.

    Match on Lambda.Unknown, Sandbox.Timedout, States.ALL, and States.TaskFailed to handle possible errors. For more information about Lambda Handled and Unhandled errors, see FunctionError in the Amazon Lambda Developer Guide.

  6. (Optional) In the Graph visualization, see the real-time graphical visualization of your workflow.

  7. Specify a name for your state machine. To do this, choose the edit icon next to the default state machine name of MyStateMachine. Then, in State machine configuration, specify a name in the State machine name box.

    For this tutorial, enter Catchfailure.

  8. (Optional) In State machine configuration, specify other workflow settings, such as state machine type and its execution role.

    For this tutorial, keep all the default selections in State machine settings.

  9. In the Confirm role creation dialog box, choose Confirm to continue.

    You can also choose View role settings to go back to State machine configuration.

    Note

    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.

Step 4: Run the state machine

After you create your state machine, you can run it.

  1. On the State machines page, choose Catchfailure.

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

  3. In the Start execution dialog box, do the following:

    1. (Optional) Enter a custom execution name to override the generated default.

      Non-ASCII names and logging

      Step Functions accepts names for state machines, executions, activities, and labels that contain non-ASCII characters. Because such characters will not work with Amazon CloudWatch, we recommend using only ASCII characters so you can track metrics in CloudWatch.

    2. (Optional) In the Input box, enter input values in JSON format to run your workflow.

    3. Choose Start execution.

    4. The Step Functions console directs you to a page that's titled with your execution ID. This page is known as the Execution Details page. On this page, you can review the execution results as the execution progresses or after it's complete.

      To review the execution results, choose individual states on the Graph view, and then choose the individual tabs on the Step details pane to view each state's details including input, output, and definition respectively. For details about the execution information you can view on the Execution Details page, see Execution details overview.

    For example, to view your custom error message, choose the CreateAccount step in Graph view, and then choose the Output tab.

    Illustrative screenshot of the output with an error message from the execution.
    Note

    You can preserve the state input with the error by using ResultPath. See Use ResultPath to include both error and input in a Catch.