Skip to content

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

fix(agent): treat missing List Operations input as empty list (#19275)

euvre38c40e64a98c
diff --git a/agent/component/list_operations.py b/agent/component/list_operations.py
index b81058e74d..31618b54ed 100644
--- a/agent/component/list_operations.py
+++ b/agent/component/list_operations.py
@@ -53,7 +53,13 @@ class ListOperations(ComponentBase, ABC):
self.input_objects = []
inputs = getattr(self._param, "query", None)
self.inputs = self._canvas.get_variable_value(inputs)
- if not isinstance(self.inputs, list):
+ if self.inputs is None:
+ # A missing/unset variable (e.g. the upstream node was routed
+ # around by a conditional branch) means "no variable passed in":
+ # operate on an empty list instead of failing the whole run.
+ # Non-list values are still a misconfiguration and keep raising.
+ self.inputs = []
+ elif not isinstance(self.inputs, list):
raise TypeError("The input of List Operations should be an array.")
self.set_input_value(inputs, self.inputs)
if self._param.operations == "nth":
diff --git a/internal/agent/component/list_operations.go b/internal/agent/component/list_operations.go
index 831a4edc2a..9c2846366e 100644
--- a/internal/agent/component/list_operations.go
+++ b/internal/agent/component/list_operations.go
@@ -298,7 +298,25 @@ func (l *ListOperationsComponent) Invoke(ctx context.Context, db *gorm.DB, _ map
}
items, ok := raw.([]any)
if !ok {
- return nil, fmt.Errorf("ListOperations: input is not a list (got %T)", raw)
+ // A nil value means the referenced variable was never written in
+ // this run — typically an upstream node routed around by a
+ // conditional branch. That is "no variable passed in", not a
+ // misconfiguration: operate on an empty list so the canvas run
+ // survives. Non-nil non-list values remain a hard error.
+ if raw == nil {
+ items = []any{}
+ } else {
+ return nil, fmt.Errorf("ListOperations: input is not a list (got %T)", raw)
+ }
+ }
+ // A typed nil []any satisfies the assertion above (ok=true, items=nil)
+ // and bypasses the unset-variable branch — e.g. an upstream component
+ // that wrote a never-appended `var out []any` into state. Normalize it
+ // to the same empty list so both nil forms are indistinguishable for
+ // the operators and the non-nil result contract holds structurally,
+ // not by each operator's slice-construction style.
+ if items == nil {
+ items = []any{}
}
var out []any
diff --git a/internal/agent/component/list_operations_test.go b/internal/agent/component/list_operations_test.go
index 1a2e671288..e92a76862a 100644
--- a/internal/agent/component/list_operations_test.go
+++ b/internal/agent/component/list_operations_test.go
@@ -517,3 +517,98 @@ func TestListOperations_InputsDocMatchesAllowlist(t *testing.T) {
}
}
}
+
+// TestListOperations_MissingInputOperatesOnEmptyList pins the fix for
+// "ListOperations errors when no variable is passed in": when the query
+// variable resolves to nil (the referenced upstream node never ran, e.g.
+// it was routed around by a conditional branch), the component must
+// operate on an empty list instead of failing the whole canvas run.
+func TestListOperations_MissingInputOperatesOnEmptyList(t *testing.T) {
+ for _, op := range []string{"nth", "head", "tail", "filter", "sort", "drop_duplicates"} {
+ c, err := NewListOperationsComponent(map[string]any{
+ "query": "cpn_never_ran@result",
+ "operations": op,
+ "n": 1,
+ })
+ if err != nil {
+ t.Fatalf("op %s: NewListOperationsComponent: %v", op, err)
+ }
+ state := canvas.NewCanvasState("run-1", "task-1")
+ ctx := canvas.WithState(t.Context(), state)
+
+ out, err := c.Invoke(ctx, nil, nil)
+ if err != nil {
+ t.Fatalf("op %s: Invoke: %v", op, err)
+ }
+ got, ok := out["result"].([]any)
+ if !ok || got == nil {
+ t.Fatalf("op %s: result should be a non-nil empty list, got %#v", op, out["result"])
+ }
+ if len(got) != 0 {
+ t.Errorf("op %s: result should be empty, got %v", op, got)
+ }
+ if out["first"] != nil || out["last"] != nil {
+ t.Errorf("op %s: first/last should be nil for empty result, got %v/%v", op, out["first"], out["last"])
+ }
+ }
+}
+
+// TestListOperations_TypedNilSliceInputOperatesOnEmptyList pins the second
+// nil form: a typed nil []any written into state (e.g. an upstream
+// component's never-appended `var out []any`) satisfies the []any assertion
+// and bypasses the unset-variable branch. Invoke must normalize it to the
+// same non-nil empty list and keep first/last nil.
+func TestListOperations_TypedNilSliceInputOperatesOnEmptyList(t *testing.T) {
+ for _, op := range []string{"nth", "head", "tail", "filter", "sort", "drop_duplicates"} {
+ c, err := NewListOperationsComponent(map[string]any{
+ "query": "cpn_nil@xs",
+ "operations": op,
+ "n": 1,
+ })
+ if err != nil {
+ t.Fatalf("op %s: NewListOperationsComponent: %v", op, err)
+ }
+ state := canvas.NewCanvasState("run-tnil", "task-tnil")
+ state.Outputs["cpn_nil"] = map[string]any{"xs": []any(nil)}
+ ctx := canvas.WithState(t.Context(), state)
+
+ out, err := c.Invoke(ctx, nil, nil)
+ if err != nil {
+ t.Fatalf("op %s: Invoke: %v", op, err)
+ }
+ got, ok := out["result"].([]any)
+ if !ok || got == nil {
+ t.Fatalf("op %s: result should be a non-nil empty list, got %#v", op, out["result"])
+ }
+ if len(got) != 0 {
+ t.Errorf("op %s: result should be empty, got %v", op, got)
+ }
+ if out["first"] != nil || out["last"] != nil {
+ t.Errorf("op %s: first/last should be nil for empty result, got %v/%v", op, out["first"], out["last"])
+ }
+ }
+}
+
+// TestListOperations_NonListInputStillErrors: a non-nil, non-list value is
+// a real misconfiguration and must keep failing loudly (#11364 contract).
+func TestListOperations_NonListInputStillErrors(t *testing.T) {
+ c, err := NewListOperationsComponent(map[string]any{
+ "query": "cpn_0@xs",
+ "operations": "head",
+ "n": 1,
+ })
+ if err != nil {
+ t.Fatalf("NewListOperationsComponent: %v", err)
+ }
+ state := canvas.NewCanvasState("run-1", "task-1")
+ state.Outputs["cpn_0"] = map[string]any{"xs": "not-a-list"}
+ ctx := canvas.WithState(t.Context(), state)
+
+ _, err = c.Invoke(ctx, nil, nil)
+ if err == nil {
+ t.Fatal("expected error for non-list input")
+ }
+ if !strings.Contains(err.Error(), "input is not a list") {
+ t.Fatalf("unexpected error: %v", err)
+ }
+}
diff --git a/test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py b/test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
index 1f25098a93..724b1c6c61 100644
--- a/test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
+++ b/test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
@@ -183,3 +183,39 @@ def test_topn_operation_alias_normalizes_to_head(monkeypatch):
param.operations = "topN"
param.check()
assert param.operations == "head"
+
+
+def _make_invoke_component(module, *, resolved):
+ component = module.ListOperations.__new__(module.ListOperations)
+ component._canvas = SimpleNamespace(get_variable_value=lambda _ref: resolved)
+ component._param = SimpleNamespace(
+ query="cpn_0@result",
+ operations="nth",
+ n=1,
+ strict=False,
+ outputs={
+ "result": {"value": []},
+ "first": {"value": None},
+ "last": {"value": None},
+ },
+ )
+ return component
+
+
+def test_invoke_treats_missing_variable_as_empty_list(monkeypatch):
+ module = _load_list_operations_module(monkeypatch)
+ component = _make_invoke_component(module, resolved=None)
+ component._invoke()
+ assert component.inputs == []
+ assert component._param.outputs["result"]["value"] == []
+ assert component._param.outputs["first"]["value"] is None
+ assert component._param.outputs["last"]["value"] is None
+
+
+def test_invoke_still_raises_for_non_list_input(monkeypatch):
+ module = _load_list_operations_module(monkeypatch)
+ component = _make_invoke_component(module, resolved="not-a-list")
+ with pytest.raises(TypeError, match="should be an array"):
+ component._invoke()