Workflow Fail Branch Architecture#

Overview#

The fail branch is a first-class workflow routing mechanism that lets a failing node redirect execution to a designated downstream "fail" edge instead of halting the entire run. In graphon's graph model, nodes that declare a fail-branch strategy are treated as exclusive branchers: only one outbound handle fires per execution — either the success path or the fail branch 1.

Dify's workflow engine delegates graph execution to the external graphon package (graphon==0.6.0) 2. Graphon owns the GraphEngine, variable pool, event routing, and built-in node implementations. Dify wires its own node logic (LLM, Agent, HTTP, etc.) into graphon's node registry via DifyNodeFactory, which acts as the integration point between the two layers.

The fail branch feature is most fully realized in the Workflow Agent Node v2 (DifyAgentNode), which implements per-output failure strategies including retries, default-value fallback, hard stop, and fail-branch routing.

Graphon Package and DifyNodeFactory#

graphon is Langgenius's open-source Python graph execution engine, pinned at graphon==0.6.0 in api/pyproject.toml. It provides:

• Queue-based GraphEngine orchestration with event-driven execution 3
• Graph parsing, validation, and shared VariablePool / GraphRuntimeState
• Built-in node implementations for common types (start, end, llm, if-else, code, http-request, tool, iteration, loop, human-input, etc.)
• Outbound edge routing, including exclusive branching for fail paths

Dify merges its own node implementations (core.workflow.nodes.*) with graphon's built-ins (graphon.nodes.*) through register_nodes(), then exposes the combined registry via DifyNodeFactory. For each node type, DifyNodeFactory.create_node() resolves the node class and injects Dify-specific dependencies (code executor, LLM model instance, HITL callbacks, output failure orchestrator, etc.) before handing the node back to graphon's engine 4.

The architectural boundary: graphon owns generic execution mechanics; Dify owns business logic (credentials, output validation, file management, HITL forms). This mirrors the HITL refactor that moved form schemas and timeout semantics from graphon back into Dify 5.

Per-Output Failure Strategy Configuration#

For the Agent Node v2, failure handling is configured per declared output rather than at the node level. The key models live in api/models/agent_config_entities.py:

• OutputErrorStrategy — three terminal strategies: STOP (fail the node hard), DEFAULT_VALUE (substitute a pre-configured value), FAIL_BRANCH (route through the fail branch edge) 6
• DeclaredOutputFailureStrategy — holds retry config (max retries, enabled flag), on_failure: OutputErrorStrategy, and default_value
• DeclaredOutputConfig — each declared output carries a failure_strategy field defaulting to a populated DeclaredOutputFailureStrategy

Because strategies are per-output, a single node run can have outputs with different strategies. The orchestrator merges them using a precedence rule: FAIL_BRANCH (rank 2) > STOP (rank 1) > DEFAULT_VALUE (rank 0) 7. If any failing output declares FAIL_BRANCH, that decision wins for the whole node — regardless of what other outputs declare.

DifyAgentNodeData itself is minimal (inherits BaseNodeData from graphon) and carries no node-level error strategy — all strategy is in the binding's declared_outputs 8.

OutputFailureOrchestrator — Decision Engine#

OutputFailureOrchestrator in api/core/workflow/nodes/agent_v2/output_failure_orchestrator.py is a stateless pure decision engine. The caller (agent_node._run) owns the retry counter and executes re-runs; the orchestrator only computes what to do next.

Four possible decisions 9:

Decision logic in decide():

1. If any failing output still has retry budget (current_attempt < max_retries), return RETRY.
2. Once retry budget is exhausted, call _merge_terminal_decisions() which picks the highest-precedence OutputErrorStrategy across all failures and maps it to a decision via _TERMINAL_STRATEGY_TO_DECISION 6.

The orchestrator is injected into DifyAgentNode by DifyNodeFactory._build_agent_node_init_kwargs() 10.

Fail Branch Trigger and Data Flow#

Triggering the Fail Branch#

Inside DifyAgentNode._run_inner(), after a successful Agent backend run, the type-check results are fed to the orchestrator 11. When the decision is TAKE_FAIL_BRANCH, the node sets:

error_type = "output_type_check_failed_fail_branch"

and yields a StreamCompletedEvent wrapping a NodeRunResult with status=FAILED 12. Graphon's engine sees this error_type and routes execution to the outbound fail branch edge.

Other failure paths (binding errors, backend errors, runtime exceptions) emit a _failure_event() with a different error_type string and do not trigger fail branch routing.

Data Available to Downstream Fail-Branch Nodes#

The _failure_event() method constructs the NodeRunResult with the following fields:

┌──────────────────────┐ TAKE_FAIL_BRANCH ┌──────────────────────┐
│ DifyAgentNode._run │ ─── StreamCompletedEvent ──▶ Fail Branch Node │
│ (type check fails) │ error_type="…fail_branch"│ reads inputs / │
│ orchestrator.decide │ │ metadata / error │
└──────────────────────┘ └──────────────────────┘
         │ RETRY / USE_DEFAULT / FAIL_NODE
         ▼
   (handled inline, no branch routing)

Static Validation at Publish Time#

A non-blocking advisory validator (PR #37131, not yet merged at research date) performs static data-flow analysis at publish time and flags any variable reference that may not be populated on a concrete execution path. Nodes with error_strategy = FAIL_BRANCH are treated as exclusive branchers in this analysis — only one handle fires per run, so cross-branch variable references are flagged as warnings 1.