feat: lead the run graph's error handler to the node that receives its output

Merged
HU
18h ago
+555-114

Summary

When a flow's error handler ran, the run graph drew its marker off the failed step, leading nowhere, as a step that looked like any other. This makes the error path readable at a glance:

  • The handler node shows the bug icon (the error handler's icon in the editor) instead of its language icon.
  • An edge leads from the handler to the node that actually receives its output, so the run reads like a try/catch whose catch produced the result.
  • In a finished run, the path the run took is drawn as plain lines and the path it did not take is dashed and faded: edges through steps that never ran, and the failed step's own way out. Where that way out leads to the handler's own target, the handler's edge replaces it.
  • A collapsed subflow says "N error handlers ran" below it when handlers ran inside; clicking it expands the subflow. A loop showing an iteration without a handler says "Error handler ran in iteration K" for the first failed iteration that ran one; clicking it opens that iteration.
  • When a collapsed subflow had both retried steps and error handlers inside, the line below it shows the retry icon and the bug icon with their counts, and clicking it opens a menu with one entry for each. Only one of the two keeps the single button ("2 steps retried inside", "2 error handlers ran").

Where the handler's output goes was checked on real runs and in worker_flow.rs (payload_from_modules gives each loop iteration, branch-all branch and branch-one branch its own inner flow job with a copy of the handler, and has_triggered_error_handler keeps outer levels from running it again):

Failed step sits inHandler's output becomesEdge goes to
a for-loop or while-loopthat iteration's entry in the loop's array (the run then ends with that array)<loop>-end
a branch-allthat branch's entry<branchall>-end
a branch-onethe branch-one's result, passed throughwhatever encloses the branch-one
a branch-one with continue on errorthe branch-one's result, and the flow carries on<branchone>-end
nothing elsethe flow's resultResult, or End of subflow inside an expanded subflow

Changes

  • processModules threads a handlerTarget down the structure tree and records it per step; the marker block draws the edge to it.
  • The handler's out edge is pushed straight into edges, not through addEdge, so it stays out of parents: the compound layout groups nodes by walking parents, and an edge from inside a branch-one to Result pulled Result into the branch's group.
  • Where the handler and its target sit in one column, the edge runs along the existing path rather than detouring around the column: a wide arc read as more confusing than the overlap.
  • The marker of an expanded subflow step hangs off the subflow's end rather than its start, since the step failed as a whole.
  • The failed step keeps its structural edge, so the steps after it stay attached; it is marked bypassed, dashed, and hidden when it leads to the node the handler's edge leads to.
  • A loop or branch that failed as a whole (its iterator threw) leaves through its end node, so that exit is dashed too.
  • Edge styles are read from run state in the renderers (edgeRunClass.ts), not baked into edge data, so a poll never rebuilds the edge set. The builder only adds static flags: whether an edge belongs to the handler, the steps at either end of an edge, and bypassed.
  • "Never ran" needs a finished run, since a step not reached yet may still run: FlowStatusViewerInner passes runDone to FlowGraphV2, which sets it on the run-status context (didNotRun).
  • The retried-inside line moves from FlowModuleSchemaItem to ModuleNode, next to the handler count, so the two can share one line and one menu (DropdownV2).
  • The handler count (nestedErrorHandlers.ts) walks the run's job tree from the frontend: a handler ran when a flow job's flow_status.failure_module.job is set. No server endpoint lists every job under a run (parent_job only matches direct children), so the walk is kept small:
    • It only goes below a job whose flow has an error handler or a subflow step, since iterations and branches only carry a copy of their flow's handler. A loop is only asked when the builder sees one of those (mayRunErrorHandler).
    • Only failed iterations and branches are asked, in the loop label and in a subflow's count alike; the loop label also stops at the first iteration that ran a handler.
    • All walks share 4 request slots, a step is only counted once it has finished, and the count is recomputed only when the step's jobs change, not on every status update.
    • Finished jobs are cached for the page's life; a walk that failed is dropped from the cache.

Not covered:

  • A failed preprocessor keeps its marker without an edge (the edge would span the whole graph).
  • An iteration that ran a handler but still succeeded is skipped by the loop label and by a subflow's count: its handler returned recover: true, or it sat in a branch-one with continue on error. Finding it would mean asking every successful iteration, which a loop of thousands cannot afford. Opening that iteration shows its handler.
  • A loop whose iterator threw is stored as Failure, but the run viewer draws it without a state, so the edge into it is dashed as not run.
  • Where the handler's edge runs down the same column as steps that never ran (branch-one below), that stretch is drawn plain, since it is the handler's path.

Demo

https://github.com/user-attachments/assets/09987991-4e1d-4973-84b5-8dcbc289b35b

Screenshots

Before is the released UI (v1.858.0), after is this branch, on the same runs.

BeforeAfter
Handler returned recover: truebeforeafter
Expanded subflow: child handler and parent handler ranbeforeafter
Collapsed subflow with handlers insidebeforeafter
Collapsed subflow with retries and a handler inside, menu openbeforeafter
Loop iteration whose last step failedbeforeafter
Branch-one: untaken branch and skipped stepsbeforeafter

Test plan

  • graphBuilder.test.ts: handler edge targets loop-end, Result through a branch-one, <branchone>-end for a continuing branch-one, sub-subflow-end in an expanded subflow; a failed last step's exit is replaced, a whole-loop failure's loop-end exit is bypassed
  • edgeRunClass.test.ts: a handler's edge stays plain next to a step that did not run; replaced, bypassed and not-run edges
  • npm run check:fast: only the 4 errors main already has; vitest on src/lib/components/graph: 39 passed
  • Job requests on opening a run, besides the run itself: a 200-iteration loop without a handler sends none for its iterations; the same loop with a handler that never ran sends 1 (the shown iteration) instead of 200; batch 9, nested subflow 7
  • Real runs on a local instance for each case in the table, checking the flow result and the drawn edges
  • Run page: top level, for-loop (iteration selector), branch-all, branch-one, branch-one with continue on error, expanded subflow
  • Count label: "2 error handlers ran" on the collapsed batch subflow; in the expanded batch loop "Error handler ran in iteration 2" shows on iteration 1 and hides on iterations 2 and 4, which draw their own handler
  • Retries and a handler in one subflow: the collapsed line shows ⟳2 and the bug 1, the menu lists "2 steps retried inside" and "1 error handler ran", and each entry expands the subflow

šŸ¤– Generated with Claude Code


Summary by cubic

Leads a flow's error handler marker to the node that actually receives its output, so a handled failure reads like a try/catch ending in a result. The run graph now also paints the run: handler edges render in red (green when the handler returns recover: true), edges through steps the finished run never reached fade and dash, and a card under a collapsed subflow or loop shows how many steps were retried or error handlers ran off-screen.

Where the handler leads

  • In a loop or branch-all, the handler's output lands in that iteration's or branch's entry, so the edge goes to <loop>-end or <branchall>-end.
  • In a branch-one it passes through the branch's result to Result, or to <branchone>-end when the branch continues on error.
  • Otherwise it ends at Result, or the subflow's end when the subflow is expanded.
  • An expanded subflow step failed as a whole, so its marker hangs off the subflow's end.

Run painting

  • Error handler cards show a bug icon, and one bar under a subflow or loop shows both "N error handlers ran" and "M steps retried inside"; with both, a small menu routes each to expanding the subflow or jumping to the iteration. Counts walk only the failed jobs where a handler could have run, fetching them a few requests at a time.
  • The handler edge stays out of parents so the layout doesn't pull Result into a branch group; the failed step keeps its structural edge so the steps after it stay attached.
  • A failed preprocessor and a failed last step inside a loop or branch still draw the marker without a usable edge; that predates this change.