Tutorial 8: Debug errors in the console - Amazon Step Functions
Debugging the invalid path Choice state errorDebugging JSON path expression errors while applying input and output filters
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).

Tutorial 8: Debug errors in the console

As you work with Step Functions, you might encounter runtime errors arising because of reasons, such as:

  • An invalid JSON path for the Variable field in the Choice state.

  • State machine definition issue, such as no matching rule defined for a Choice state.

  • Invalid JSON path expressions while applying filters to manipulate input and output.

  • Task failures because of a Lambda function exception.

  • IAM permission errors.

In this tutorial, you’ll learn about debugging some of these errors using the Step Functions console. For more information, see Error handling in Step Functions.

Debugging the invalid path Choice state error

When you specify an incorrect or unresolvable JSON path in the Variable field of the Choice state or do not define a matching rule in the Choice state, you receive an error while running your workflow.

To illustrate the invalid path error, this tutorial introduces a Choice state error in your workflow. You’ll use the CreditCardWorkflow state machine and edit its definition to introduce the error.

  1. Open the Step Functions console and then choose the CreditCardWorkflow state machine.

  2. Choose Edit to edit the state machine definition. Make the change highlighted in the following code to your state machine definition.

    {
  "Comment": "A description of my state machine",
  "StartAt": "Get credit limit",
  "States": {
    "Get credit limit": {
      ...
      ...
    },
    "Credit applied >= 5000?": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.Payload",
          "NumericLessThan": 5000,
          "Next": "Auto-approve limit"
        },
        {
          "Variable": "$.Payload",
          "NumericGreaterThanEquals": 5000,
          "Next": "Wait for human approval"
        }
        ],
        "Default": "Wait for human approval"
    },
    ...
    ...
  }
}

  3. Choose Save and then choose Save anyway.

  4. Run the state machine.

  5. On the Execution Details page of your state machine execution, do one of the following:

    1. Choose Cause on the error message to view the reason for execution failure.

    2. Choose Show step detail on the error message to view the step that caused the error.

  6. In the Input & Output tab of the Step details section, choose the Advanced view toggle button to see the input and output data transfer path for a selected state.

  7. In Graph view, make sure Credit applied >= 5000? is selected and do the following:

    1. View the state’s input value in Input box.

    2. Choose the Definition tab, and notice the JSON path specified for the Variable field.

      The input value for the Credit applied >= 5000? state is a numeric value, while you’ve specified the JSON path for the input value as $.Payload. During the state machine execution, the Choice state cannot resolve this JSON path because it doesn’t exist.

  8. Edit the state machine to specify the Variable field value as $.

    {
  "Comment": "A description of my state machine",
  "StartAt": "Get credit limit",
  "States": {
    "Get credit limit": {
      ...
      ...
    },
    "Credit applied >= 5000?": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$",
          "NumericLessThan": 5000,
          "Next": "Auto-approve limit"
        },
        {
          "Variable": "$",
          "NumericGreaterThanEquals": 5000,
          "Next": "Wait for human approval"
        }
        ],
        "Default": "Wait for human approval"
    },
    ...
    ...
  }
}

Debugging JSON path expression errors while applying input and output filters

As you work with the input and output filters, you might encounter runtime errors arising because of specifying invalid JSON path expressions.

The following example uses the WorkflowInputOutput state machine you created in Tutorial 5 and demonstrates a scenario where you use the ResultSelector filter to select portions of the task output.

  1. Apply the ResultSelector filter to choose a portion of the task output for the Verify identity step. To do this, edit your state machine definition as follows:

    {
  "StartAt": "Verify identity",
  "States": {
    "Verify identity": {
      "Type": "Task",
      "Resource": "arn:aws:states:::lambda:invoke",
      "Parameters": {
        "FunctionName": "arn:aws-cn:lambda:us-west-2:123456789012:function:check-identity",
        "Payload": {
          "email": "jdoe@example.com",
          "ssn": "123-45-6789"
        }
      },
      ...
      ...
      "ResultSelector": {
        "identity.$": "$.Payload.body.message"
 }",
      "End": true
    }
  }
}

  2. Run the state machine.

  3. On the Execution Details page of your state machine execution, do the following:

    1. Choose Cause on the error message to view the reason for execution failure.

    2. Choose Show step detail on the error message to view the step that caused the error.

  4. In the error message, note that the contents of the $.Payload.body node is an escaped JSON string. The error has occurred because you cannot refer to a string using the JSON path notation.

  5. To refer to the $.Payload.body.message node, do the following:

    1. Use the States.StringToJSON intrinsic function to first convert the string to a JSON format.

    2. Specify the JSON path for the $.Payload.body.message node inside the intrinsic function.

      "ResultSelector": {
 "identity.$":"States.StringToJson($.Payload.body.message)"
}

  6. Run the state machine again.