Fail workflow state - AWS Step Functions
Fail state definition examples

Fail workflow state

Managing state and transforming data

Learn about Passing data between states with variables and Transforming data with JSONata.

A Fail state ("Type": "Fail") stops the execution of the state machine and marks it as a failure, unless it is caught by a Catch block.

The Fail state only allows the use of Type and Comment fields from the set of common state fields. In addition, the Fail state allows the following fields.

Cause (Optional)

A custom string that describes the cause of the error. You can specify this field for operational or diagnostic purposes.

In JSONata states, you can also specify a JSONata expression.

CausePath (Optional, JSONPath only)

If you want to provide a detailed description about the cause of the error dynamically from the state input using a reference path, use CausePath. When resolved, the reference path must select a field that contains a string value.

You can also specify CausePath using an intrinsic function that returns a string. These intrinsics are: States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, and States.UUID.

Important

  • You can specify either Cause or CausePath, but not both in your Fail state definition.

  • As an information security best practice, we recommend that you remove any sensitive information or internal system details from the cause description.

Error (Optional)

An error name that you can provide to perform error handling using Retry or Catch fields. You can also provide an error name for operational or diagnostic purposes.

In JSONata states, you can also specify a JSONata expression.

ErrorPath (Optional, JSONPath only)

If you want to provide a name for the error dynamically from the state input using a reference path, use ErrorPath. When resolved, the reference path must select a field that contains a string value.

You can also specify ErrorPath using an intrinsic function that returns a string. These intrinsics are: States.Format, States.JsonToString, States.ArrayGetItem, States.Base64Encode, States.Base64Decode, States.Hash, and States.UUID.

Important

  • You can specify either Error or ErrorPath, but not both in your Fail state definition.

  • As an information security best practice, we recommend that you remove any sensitive information or internal system details from the error name.

Because Fail states always exit the state machine, they have no Next field and don't require an End field.

Fail state definition examples

The following Fail state definition example specifies static Error and Cause field values.

"FailState": {
  "Type": "Fail",
  "Cause": "Invalid response.",
  "Error": "ErrorA"
}

The following Fail state definition example uses reference paths dynamically to resolve the Error and Cause field values.

"FailState": {
  "Type": "Fail",
  "CausePath": "$.Cause",
  "ErrorPath": "$.Error"
}

The following Fail state definition example uses the States.Format intrinsic function to specify the Error and Cause field values dynamically.

"FailState": {
  "Type": "Fail",
  "CausePath": "States.Format('This is a custom error message for {}, caused by {}.', $.Error, $.Cause)",
  "ErrorPath": "States.Format('{}', $.Error)"
}