Use the Fail state to terminate a workflow - CloudFlow

The Fail state terminates a flow with a custom error, similar to raise in Python or throw in Java. When a flow reaches a Fail state, all states in the current scope stop running and the flow ends.

In a typical flow definition, each state transitions to the next after it completes. A Fail state breaks this pattern -- no next state runs.

Note Unlike a Succeed state, which waits for the current scope to complete before ending the flow, a Fail state ends the flow with an error.

Attributes

Attribute	Type	Required	Description	Example
`Name`	string	Yes	State name.	my state
`Description`	string	No	State description.	describe it here
`Type`	string	Yes	Must be `Fail`.	Fail
`InputConstructor`	map[string]any	No	Input constructor. See InputConstructor.	--
`OutputConstructor`	map[string]any	No	Output constructor. See OutputConstructor.	--
`Code`	string	No	Error code for programmatic identification. Use `Code` to categorize failures for diagnostics or error handling.	customBizCode
`Detail`	string	Yes	Human-readable error description.	my custom error

Every Fail state requires a Detail value that describes the error. Code is optional but recommended -- it provides a machine-readable identifier that makes failures easier to diagnose.

Note Tip: Avoid exposing internal system details or sensitive information in Code or Detail values, because these values may be visible in error outputs.

How it relates to a Pass state

A Fail state behaves like a Pass state with End: true, except that it also returns an error. Both end the flow at the current point, but a Fail state also returns an error specified by Code and Detail.

Examples

Terminate a flow based on a condition

This flow uses a Choice state to evaluate an input condition. If $Input.status equals "true", the flow proceeds to Pass1 and completes normally. Otherwise, the flow falls through to the default branch and ends with a Fail state.

Type: StateMachine
Name: my-workflow
SpecVersion: v1
Description: " "
StartAt: Choice1
States:
  - Type: Choice
    Name: Choice1
    Branches:
      - Condition: $Input.status == "true"
        Next: Pass1
    Default: Fail1
  - Type: Fail
    Name: Fail1
    Code: "customBizCode"
    End: true
  - Type: Pass
    Name: Pass1
    End: true

When Choice1 evaluates the condition and no branch matches, the flow transitions to Fail1. The entire flow ends with error code customBizCode.

Return a static error

At its simplest, a Fail state needs a Detail value and optionally a Code:

- Type: Fail
  Name: ValidationError
  Code: "INVALID_INPUT"
  Detail: "Required field 'orderId' is missing"
  End: true

Use descriptive error codes

Choose error codes that clearly identify the failure category:

# Payment processing failure
- Type: Fail
  Name: PaymentFailed
  Code: "PAYMENT_DECLINED"
  Detail: "Payment gateway returned a decline response"
  End: true

# Resource not found
- Type: Fail
  Name: NotFound
  Code: "RESOURCE_NOT_FOUND"
  Detail: "The specified order does not exist"
  End: true