Debug errors in Step Functions console - AWS Step Functions
Debugging the invalid path Choice state errorDebugging JSON path expression errors while applying input and output filtersConclusion and next steps

Debug errors in Step Functions console

In the previous topic, Configure input and output, you learned about filtering and manipulating data. In your state machine configuration and data selection you might encounter errors. In this final topic, you’ll be introduced to debugging runtime errors using the Step Functions console.

You might encounter runtime errors, 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.

Tip

For additional error handling options, see Handling errors in Step Functions workflows.

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:lambda:us-east-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.

Conclusion and next steps

Congratulations! You have reached the end of Getting started tutorial with Step Functions.

Cleanup

Now that you have completed Getting Started, it is a good practice to clean up (delete) any resources you no longer want to use. Cleaning up AWS resources prevents your account from incurring any further charges.