Skip to content

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

fix(api): return the full error tuple when both id and ids are given to list documents (#19280)

MarMar Labsfa52804fa38f
diff --git a/api/apps/restful_apis/document_api.py b/api/apps/restful_apis/document_api.py
index 4f5b1b2c5b..0b81320562 100644
--- a/api/apps/restful_apis/document_api.py
+++ b/api/apps/restful_apis/document_api.py
@@ -941,7 +941,7 @@ def _get_docs_with_request(req, dataset_id: str):
except ValueError as e:
return RetCode.ARGUMENT_ERROR, str(e), [], 0
if doc_id and len(doc_ids) > 0:
- return RetCode.DATA_ERROR, f"Should not provide both 'id':{doc_id} and 'ids'{doc_ids}"
+ return RetCode.DATA_ERROR, f"Should not provide both 'id':{doc_id} and 'ids'{doc_ids}", [], 0
if len(doc_ids) > 0:
doc_ids_filter = doc_ids
diff --git a/test/unit_test/api/apps/restful_apis/test_list_docs_id_ids_conflict.py b/test/unit_test/api/apps/restful_apis/test_list_docs_id_ids_conflict.py
new file mode 100644
index 0000000000..e4656edba4
--- /dev/null
+++ b/test/unit_test/api/apps/restful_apis/test_list_docs_id_ids_conflict.py
@@ -0,0 +1,223 @@
+#
+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Regression test for `GET /datasets/<dataset_id>/documents?id=..&ids=..`.
+
+`_get_docs_with_request` builds a DATA_ERROR for the both-provided case, but
+returned it as a 2-tuple while `list_docs` unpacks 4, so the request raised
+`ValueError` and the caller got EXCEPTION_ERROR with a Python repr instead of
+the error the helper wrote.
+
+The cases below pin the shape (four values) and the error the helper already
+builds.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+
+import pytest
+from werkzeug.datastructures import MultiDict
+
+from common.constants import RetCode
+
+DATASET_ID = "kb-1"
+OWNED_DOC_ID = "doc-owned"
+OTHER_DOC_ID = "doc-other"
+
+
+class _PassthroughManager:
+ def route(self, *_args, **_kwargs):
+ return lambda func: func
+
+
+class _LenientModule(ModuleType):
+ """A stub module that yields a harmless placeholder for any attribute that
+ wasn't explicitly provided. document_api.py's top-level
+ `from <mod> import a, b` only needs every imported name to exist; symbols
+ that are not on the list_docs path are never called, so a no-op placeholder
+ is safe. This keeps the test from rotting each time document_api.py grows
+ an import.
+ """
+
+ def __getattr__(self, _name):
+ return lambda *_a, **_k: None
+
+
+def _stub(monkeypatch, name, **attrs):
+ mod = _LenientModule(name)
+ for key, value in attrs.items():
+ setattr(mod, key, value)
+ monkeypatch.setitem(sys.modules, name, mod)
+ return mod
+
+
+def _load_document_api(monkeypatch, *, args, owned_doc_ids):
+ """Load document_api.py with the minimum stubs to exercise list_docs.
+
+ `common.constants`, `api.db` and `api.utils.pagination_utils` are the real
+ modules, so RetCode, VALID_FILE_TYPES and the id-count limit are the ones
+ the route actually uses.
+ """
+ request_stub = SimpleNamespace(method="GET", args=MultiDict(args))
+
+ def _document_query(**kwargs):
+ return [SimpleNamespace()] if kwargs.get("id") in owned_doc_ids else []
+
+ _stub(
+ monkeypatch,
+ "api.apps",
+ AUTH_JWT="jwt",
+ AUTH_API="api",
+ AUTH_BETA="beta",
+ current_user=SimpleNamespace(id="tenant-1"),
+ login_required=lambda func=None, **_kwargs: (lambda f: f) if func is None else func,
+ )
+ _stub(monkeypatch, "api.apps.services.document_api_service", map_doc_keys=lambda doc: doc)
+ _stub(
+ monkeypatch,
+ "api.db.db_models",
+ API4Conversation=SimpleNamespace(),
+ # Applied as `@DB.connection_context()` at module level, so it has to
+ # hand back an identity decorator.
+ DB=SimpleNamespace(connection_context=lambda *_a, **_k: lambda func: func),
+ Task=SimpleNamespace(),
+ )
+ _stub(monkeypatch, "api.db.services", duplicate_name=lambda *_a, **_k: "")
+ _stub(monkeypatch, "api.db.services.doc_metadata_service", DocMetadataService=SimpleNamespace(get_flatted_meta_by_kbs=lambda *_a, **_k: {}))
+ _stub(monkeypatch, "api.db.services.document_counter_service", release_reparse_counters=lambda *_a, **_k: None)
+ _stub(
+ monkeypatch,
+ "api.db.services.document_service",
+ DocumentService=SimpleNamespace(
+ # Only the id/name ownership probes in _get_docs_with_request call
+ # this; a hit is a non-empty list.
+ query=_document_query,
+ get_by_kb_id=lambda *_a, **_k: ([], 0),
+ ),
+ )
+ _stub(monkeypatch, "api.db.services.file2document_service", File2DocumentService=SimpleNamespace())
+ _stub(monkeypatch, "api.db.services.file_service", FileService=SimpleNamespace())
+ _stub(monkeypatch, "api.db.services.knowledgebase_service", KnowledgebaseService=SimpleNamespace(accessible=lambda *_a, **_k: True))
+ _stub(monkeypatch, "api.db.services.canvas_service", UserCanvasService=SimpleNamespace())
+ _stub(monkeypatch, "api.common.check_team_permission", check_kb_team_permission=lambda *_a, **_k: True)
+ _stub(monkeypatch, "api.db.services.task_service", TaskService=SimpleNamespace(), cancel_all_task_of=lambda *_a, **_k: None)
+ _stub(
+ monkeypatch,
+ "api.utils.api_utils",
+ # Record what the route hands back so a test can read the code the
+ # response carries.
+ get_data_error_result=lambda message="", code=RetCode.DATA_ERROR, data=False: {"code": code, "message": message},
+ get_error_data_result=lambda message="", **_k: {"code": RetCode.DATA_ERROR, "message": message},
+ get_json_result=lambda *_a, **kwargs: {"code": RetCode.SUCCESS, "data": kwargs.get("data")},
+ server_error_response=lambda e: {"code": RetCode.EXCEPTION_ERROR, "message": repr(e)},
+ add_tenant_id_to_kwargs=lambda func: func,
+ get_request_json=lambda: {},
+ # Used as `@validate_request(...)` at module level, so it must return an
+ # identity decorator (the lenient fallback returns None and `@None`
+ # raises TypeError during import).
+ validate_request=lambda *_a, **_k: lambda func: func,
+ )
+ _stub(monkeypatch, "api.utils.validation_utils", validate_and_parse_json_request=lambda *_a, **_k: ({}, None))
+ _stub(monkeypatch, "common.settings", retriever=SimpleNamespace(), docStoreConn=SimpleNamespace(), STORAGE_IMPL=SimpleNamespace())
+ _stub(monkeypatch, "common.metadata_utils", turn2jsonschema=lambda meta: meta)
+ _stub(monkeypatch, "common.misc_utils", get_uuid=lambda: "uuid")
+ _stub(monkeypatch, "common.ssrf_guard", assert_url_is_safe=lambda *_a, **_k: None)
+ _stub(monkeypatch, "api.utils.file_utils", filename_type=lambda *_a, **_k: None, thumbnail=lambda *_a, **_k: None)
+ _stub(monkeypatch, "api.utils.file_response", apply_preview_file_response_headers=lambda *_a, **_k: None)
+ _stub(monkeypatch, "api.utils.web_utils", CONTENT_TYPE_MAP={}, is_valid_url=lambda *_a, **_k: True)
+
+ quart_stub = _LenientModule("quart")
+ quart_stub.request = request_stub
+ monkeypatch.setitem(sys.modules, "quart", quart_stub)
+
+ # parents[5] = repo root from test/unit_test/api/apps/restful_apis/<file>
+ repo_root = Path(__file__).resolve().parents[5]
+ module_path = repo_root / "api" / "apps" / "restful_apis" / "document_api.py"
+ spec = importlib.util.spec_from_file_location("test_document_api_module", module_path)
+ module = importlib.util.module_from_spec(spec)
+ # `manager` must exist before exec so the @manager.route decorators run.
+ module.manager = _PassthroughManager()
+ monkeypatch.setitem(sys.modules, "test_document_api_module", module)
+ spec.loader.exec_module(module)
+
+ # Pin the module globals list_docs resolves at call time. The sys.modules
+ # stubs only guarantee the import succeeds: in a full environment, where a
+ # real module is already loaded, `from x import y` binds the real name and
+ # the stub is bypassed. Rebinding here makes the run identical in the
+ # bare-stub and full-dependency cases.
+ module.request = request_stub
+ module.KnowledgebaseService = sys.modules["api.db.services.knowledgebase_service"].KnowledgebaseService
+ module.DocumentService = sys.modules["api.db.services.document_service"].DocumentService
+ module.DocMetadataService = sys.modules["api.db.services.doc_metadata_service"].DocMetadataService
+ api_utils = sys.modules["api.utils.api_utils"]
+ module.get_data_error_result = api_utils.get_data_error_result
+ module.get_error_data_result = api_utils.get_error_data_result
+ module.get_json_result = api_utils.get_json_result
+ module.server_error_response = api_utils.server_error_response
+ module.map_doc_keys = lambda doc: doc
+ return module
+
+
+class TestListDocsIdAndIdsConflict:
+ """`id` together with `ids` must answer with the helper's own error."""
+
+ def test_helper_returns_four_values_for_id_and_ids(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """The both-provided branch returns what `list_docs` unpacks.
+
+ Before the fix this branch returned two values, so the unpack at the
+ call site raised ValueError and the error below never reached anyone.
+ """
+ module = _load_document_api(
+ monkeypatch,
+ args=[("id", OWNED_DOC_ID), ("ids", OTHER_DOC_ID)],
+ owned_doc_ids={OWNED_DOC_ID},
+ )
+ result = module._get_docs_with_request(module.request, DATASET_ID)
+
+ assert len(result) == 4, f"list_docs unpacks 4 values, helper returned {len(result)}: {result}"
+ err_code, err_msg, payload, total = result
+ assert err_code == RetCode.DATA_ERROR
+ assert err_msg.startswith("Should not provide both")
+ assert payload == []
+ assert total == 0
+
+ def test_route_answers_with_the_helper_code(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ """End to end: the response carries the code the helper chose.
+
+ Before the fix the unpack raised and Quart's error handler answered
+ EXCEPTION_ERROR with `repr(ValueError(...))` as the message. The call
+ below routes an escaping exception through `server_error_response` the
+ way the app does with `app.errorhandler(Exception)`
+ (`api/apps/__init__.py:69`), so a raise reads as the response the
+ client would get.
+ """
+ module = _load_document_api(
+ monkeypatch,
+ args=[("id", OWNED_DOC_ID), ("ids", OTHER_DOC_ID)],
+ owned_doc_ids={OWNED_DOC_ID},
+ )
+ helper_code, helper_msg = module._get_docs_with_request(module.request, DATASET_ID)[:2]
+
+ try:
+ response = module.list_docs(dataset_id=DATASET_ID, tenant_id="tenant-1")
+ except Exception as e: # noqa: BLE001 - mirrors the app's blanket handler
+ response = module.server_error_response(e)
+
+ assert response["code"] != RetCode.EXCEPTION_ERROR, response
+ assert response["code"] == helper_code
+ assert response["message"] == helper_msg