Fail workflow `flow.fail`

A fail node commits a failed terminal outcome after workflow logic has determined that execution cannot continue. error_expression builds the final message from input and committed results. Use it for a business-rule rejection, failed compensation, or another explicitly unrecoverable state. Temporary network errors and retryable task failures belong in step retry handling instead of closing the run early.

Error content

The message should give an operator useful business context, such as the failed stage, an external reference, and a practical next action. Tokens, credentials, complete request headers, sensitive input, and unredacted remote responses must stay out of terminal text. Put deeper diagnostics in controlled telemetry under a correlation ID and keep only a safe summary in history.

A string may arrive through the error data port, or the expression may compose fields. The final text must be replay-stable and cannot include a newly read clock, random identifier, or live remote state. The node has no outgoing ports. If the process can still compensate, degrade, or request human repair, perform that work before entering this terminal node.

Operations and alerts

Test missing error fields, redaction, duplicate terminal submission, cleanup failure during cancellation, and failure caused by exhausted step retries. Monitoring can distinguish explicit fail nodes from a task that failed the run directly. The first usually records a business decision, while the second points to execution behavior. Alert on stable error codes or correlation fields rather than matching an entire natural-language message that may evolve.

Use it when workflow logic has determined that the run cannot continue. The error expression should give operators actionable business context.

Runtime behavior

The failure event closes the current segment and stores the evaluated message. It remains distinguishable from a step failure caused directly by retry exhaustion.

Node contract

Type: flow.fail
Role: Durable runtime command
Runtime binding: fail
Durable identity: Defined by graph structure

Configuration properties

Property	Type and control	Default	Rules
`error_expression`Failure message	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"concat","values":[{"op":"literal","value":"Workflow failed: "},{"op":"field","path":"input.reason"}]}}`	Build the final error message from text and workflow data.Required

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Input	`error`Error	data	`String`

Node JSON example

The CLI creates the same structure from manifest defaults. Canvas position, title, and selection are presentation data.

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-fail",
  "data": {
    "error_expression": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "concat",
        "values": [
          {
            "op": "literal",
            "value": "Workflow failed: "
          },
          {
            "op": "field",
            "path": "input.reason"
          }
        ]
      }
    },
    "type": "flow.fail"
  }
}

CLI usage

Inspect the installed manifest first, then create the node and validate the complete workflow. Every command emits JSON.

Terminal

a3s-flow node flow.fail --pretty
a3s-flow new flow.fail --id example-flow-fail --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill usage

The package includes the a3s-flow Skill. It queries the CLI catalog before creating, validating, compiling, and digesting a workflow.

Prompt

Use $a3s-flow to add the "flow.fail" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

Keep tokens and complete external responses out of error text.
Cleanup failure may use this outcome during cancellation.
Recoverable errors should use the step failure branch first.

#Fail workflow flow.fail

#Error content

#Operations and alerts