feat: lead the run graph's error handler to the node that receives its output
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 in | Handler's output becomes | Edge goes to |
|---|---|---|
| a for-loop or while-loop | that iteration's entry in the loop's array (the run then ends with that array) | <loop>-end |
| a branch-all | that branch's entry | <branchall>-end |
| a branch-one | the branch-one's result, passed through | whatever encloses the branch-one |
| a branch-one with continue on error | the branch-one's result, and the flow carries on | <branchone>-end |
| nothing else | the flow's result | Result, or End of subflow inside an expanded subflow |
Changes
processModulesthreads ahandlerTargetdown 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 throughaddEdge, so it stays out ofparents: the compound layout groups nodes by walkingparents, 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 edgedata, 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, andbypassed. - "Never ran" needs a finished run, since a step not reached yet may still run:
FlowStatusViewerInnerpassesrunDonetoFlowGraphV2, which sets it on the run-status context (didNotRun). - The retried-inside line moves from
FlowModuleSchemaItemtoModuleNode, 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'sflow_status.failure_module.jobis set. No server endpoint lists every job under a run (parent_jobonly 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.
- 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 (
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.
| Before | After | |
|---|---|---|
Handler returned recover: true | ![]() | ![]() |
| Expanded subflow: child handler and parent handler ran | ![]() | ![]() |
| Collapsed subflow with handlers inside | ![]() | ![]() |
| Collapsed subflow with retries and a handler inside, menu open | ![]() | ![]() |
| Loop iteration whose last step failed | ![]() | ![]() |
| Branch-one: untaken branch and skipped steps | ![]() | ![]() |
Test plan
-
graphBuilder.test.ts: handler edge targetsloop-end, Result through a branch-one,<branchone>-endfor a continuing branch-one,sub-subflow-endin an expanded subflow; a failed last step's exit isreplaced, a whole-loop failure'sloop-endexit isbypassed -
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 onsrc/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>-endor<branchall>-end. - In a branch-one it passes through the branch's result to Result, or to
<branchone>-endwhen 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
parentsso 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.











