Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(canvas): clarify unmatched Switch routing errors (#20038)

Sbaaoui Idrissf43b10e52424
diff --git a/internal/agent/canvas/multibranch.go b/internal/agent/canvas/multibranch.go
index 8cf1b37ba5..3eb23f5d0b 100644
--- a/internal/agent/canvas/multibranch.go
+++ b/internal/agent/canvas/multibranch.go
@@ -74,14 +74,13 @@ func isBranchableControl(name string) bool {
}
// wireMultiBranches registers an eino MultiBranch on every
-// branchable parent that has at least two declared downstream
-// children. Pass-2 already wired AddInput edges from parent to each
+// branchable parent that has at least one declared downstream
+// child. Pass-2 already wired AddInput edges from parent to each
// child; the branch adds the control-only gating so only the
// chosen child fires at runtime.
//
// The function is a no-op for:
-// - parents with < 2 downstreams (a single-child "switch" is
-// degenerate — no branching needed, AddInput is enough)
+// - parents with no downstreams
// - parents inside loop subgraphs (their children live in the
// loop's sub-workflow; the outer graph can't see them)
// - Loop cpns themselves (their children are inside the loop
@@ -122,13 +121,8 @@ func wireMultiBranches(
}
endNodes[child] = true
}
- if len(endNodes) < 2 {
- // Either no outer-graph children, or fewer than
- // two — a MultiBranch with < 2 end-nodes is
- // either meaningless (0/1 end-nodes) or
- // equivalent to plain AddInput. Skip it so we
- // don't pay the branch-evaluation cost when the
- // DSL doesn't actually branch.
+ if len(endNodes) == 0 {
+ // There is no valid outer-graph child to route to.
continue
}
endNodesList := make([]string, 0, len(endNodes))
diff --git a/internal/agent/canvas/multibranch_test.go b/internal/agent/canvas/multibranch_test.go
index cbcd9b7c0a..ce1a05bff2 100644
--- a/internal/agent/canvas/multibranch_test.go
+++ b/internal/agent/canvas/multibranch_test.go
@@ -17,8 +17,8 @@
// multibranch_test.go — MultiBranch integration tests.
//
// The canvas scheduler (scheduler.go) installs an eino MultiBranch on
-// every Switch / Categorize parent that has at least two declared
-// downstream children. This file exercises two layers:
+// every Switch / Categorize parent that has at least one declared
+// downstream child. This file exercises two layers:
//
// 1. Pure unit tests for makeSwitchBranchCondition — the closure
// that turns outputs["_next"] into an end-node set (map[string]bool).
@@ -103,6 +103,20 @@ func TestMakeSwitchBranchCondition_UnknownKey(t *testing.T) {
}
}
+// TestMakeSwitchBranchCondition_SingleChildUnmatched: a one-child Switch
+// must not fall through to its only static edge when the selected target is
+// absent or different.
+func TestMakeSwitchBranchCondition_SingleChildUnmatched(t *testing.T) {
+ cond := makeSwitchBranchCondition(map[string]bool{"if_branch": true})
+ got, err := cond(t.Context(), map[string]any{"_next": []any{"else_branch"}})
+ if err != nil {
+ t.Fatalf("cond: %v", err)
+ }
+ if len(got) != 0 {
+ t.Errorf("cond on unmatched single-child target = %v, want empty map", got)
+ }
+}
+
// TestMakeSwitchBranchCondition_KnownKey: the happy path — a valid
// cpn_id is passed through as a single-entry map.
func TestMakeSwitchBranchCondition_KnownKey(t *testing.T) {
@@ -185,10 +199,9 @@ func TestWireMultiBranches_NoBranchable(t *testing.T) {
}
}
-// TestWireMultiBranches_SingleChildSkipped: a Switch with only one
-// downstream child is degenerate — branch is meaningless. The
-// helper should skip it and the AddInput edge handles invocation.
-func TestWireMultiBranches_SingleChildSkipped(t *testing.T) {
+// TestWireMultiBranches_SingleChild: a Switch with one downstream child
+// still needs a branch so an unmatched condition cannot execute it.
+func TestWireMultiBranches_SingleChild(t *testing.T) {
c := &Canvas{
Components: map[string]CanvasComponent{
"sw": {
@@ -200,8 +213,8 @@ func TestWireMultiBranches_SingleChildSkipped(t *testing.T) {
}
wf := compose.NewWorkflow[map[string]any, map[string]any]()
regs := wireMultiBranches(wf, c, nil)
- if len(regs) != 0 {
- t.Errorf("expected no branch for single-child Switch, got %d: %+v", len(regs), regs)
+ if len(regs) != 1 {
+ t.Errorf("expected one branch for single-child Switch, got %d: %+v", len(regs), regs)
}
}
diff --git a/internal/service/agent.go b/internal/service/agent.go
index d98897c745..f81ab5708a 100644
--- a/internal/service/agent.go
+++ b/internal/service/agent.go
@@ -2367,7 +2367,7 @@ func (s *AgentService) buildRunFunc(canvasID string, versionRow *entity.UserCanv
return state, nil
}
s.markRunFailed(ctx2, runID, "invoke: "+err.Error())
- return nil, fmt.Errorf("canvas invoke: %w", err)
+ return nil, canvasInvokeError(err)
}
// Emit message + message_end (mirrors Python's ans dict).
@@ -2896,6 +2896,18 @@ func shouldTreatAsCompletedLoopRun(err error, answer string) bool {
return strings.Contains(msg, "[GraphRunError] no tasks to execute")
}
+func canvasInvokeError(err error) error {
+ if err == nil {
+ return nil
+ }
+ msg := err.Error()
+ if strings.Contains(msg, "[GraphRunError] no tasks to execute") &&
+ strings.Contains(msg, "last completed nodes: [Switch:") {
+ return errors.New("canvas invoke: Switch routing stopped because no connected branch matched the condition; check the Switch branches")
+ }
+ return fmt.Errorf("canvas invoke: %w", err)
+}
+
// markRunSucceeded records the run as completed successfully via
// the Kvrocks-backed RunTracker. No-op when tracker is nil (test path)
// or when the underlying Redis call fails (degraded boot).
diff --git a/internal/service/agent_deferred_failure_test.go b/internal/service/agent_deferred_failure_test.go
index 289b07d352..8e24b4ba26 100644
--- a/internal/service/agent_deferred_failure_test.go
+++ b/internal/service/agent_deferred_failure_test.go
@@ -41,6 +41,18 @@ func TestDeferredAgentStreamFailureText(t *testing.T) {
}
}
+func TestCanvasInvokeErrorForUnmatchedSwitch(t *testing.T) {
+ got := canvasInvokeError(errors.New("[GraphRunError] no tasks to execute, last completed nodes: [Switch:Route]"))
+ if got.Error() != "canvas invoke: Switch routing stopped because no connected branch matched the condition; check the Switch branches" {
+ t.Fatalf("got %q", got)
+ }
+
+ original := errors.New("[GraphRunError] no tasks to execute, last completed nodes: [Message:Done]")
+ if got := canvasInvokeError(original); !errors.Is(got, original) {
+ t.Fatalf("generic graph error lost its cause: %v", got)
+ }
+}
+
// An Agent whose chat model is unavailable fails through its `_ERROR`
// output; the downstream Message records the failure while consuming the
// deferred stream. The run must keep that failure text in the chat message