For AI agents: the complete documentation index is available at https://a3s-lab.github.io/Flow/en/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/Flow/en/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/Flow/en/nodes/fail.md.
A3S Flow
  • English
  • v1.1.0

      • 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

      PropertyType and controlDefaultRules
      error_expressionFailure messagedictA3SFlowExpressionInput{"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

      DirectionPort IDKindValue types
      InputinIncontrolFlowControl
      InputerrorErrordataString

      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.