{"record":{"id":"39a7348e54c658f0","repo":"iflytek/astron-agent","slug":"ragflow-ragerror-retrieval-failed-e","errorCode":"RAGFLOW_RAGError","errorMessage":"RAGFlow retrieval failed: {e}","messagePattern":"RAGFlow retrieval failed: (.+?)","errorType":"error_code","errorClass":"ThirdPartyException","httpStatus":null,"severity":"error","filePath":"core/knowledge/service/impl/ragflow_strategy.py","lineNumber":83,"sourceCode":"                doc_ids=doc_ids,\n                top_k=effective_top_k,\n                threshold=threshold or 0,\n                ext=ext,\n            )\n            return await self._execute_retrieval(\n                payload=payload,\n                query=query,\n                threshold=threshold or 0,\n                effective_top_k=effective_top_k,\n            )\n\n        except CustomException:\n            raise\n        except ThirdPartyException:\n            raise\n        except Exception as e:\n            logger.error(\"RAGFlow query exception: %s\", e)\n            raise ThirdPartyException(\n                msg=f\"RAGFlow retrieval failed: {e}\",\n                e=CodeEnum.RAGFLOW_RAGError,\n            ) from e\n\n    async def _resolve_query_datasets(\n        self, dataset_ids: Optional[List[str]]\n    ) -> List[str]:\n        \"\"\"Return requested dataset ids or the default dataset id.\"\"\"\n        if not dataset_ids:\n            default_name = RagflowUtils.get_default_dataset_name()\n            ds_id = await RagflowUtils.ensure_dataset(default_name)\n            return [ds_id] if ds_id else []\n        return list(dataset_ids)\n\n    async def _resolve_dataset_id(\n        self,\n        dataset_id_input: Optional[str],\n        group: Optional[str] = None,","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/service/impl/ragflow_strategy.py#L65-L101","documentation":"Catch-all wrapper in RagflowRAGStrategy.query (core/knowledge/service/impl/ragflow_strategy.py:83). Any unexpected exception during the RAGFlow retrieval pipeline — dataset resolution, payload construction, or response conversion — that is not already a CustomException or ThirdPartyException is re-raised as a ThirdPartyException with code RAGFLOW_RAGError. It signals that the knowledge-retrieval call against the RAGFlow backend failed for an unclassified reason.","triggerScenarios":"Calling strategy.query(...) when: _resolve_query_datasets raises (network/HTTP error to RAGFlow or ensure_dataset fails), _build_retrieval_payload gets unexpected input, _execute_retrieval raises an exception other than ThirdPartyException (e.g. malformed response missing 'code' key, JSON decode failure), or convert_ragflow_query_response throws. CustomException/ThirdPartyException are re-raised untouched, so only non-classified exceptions land here.","commonSituations":"RAGFlow service is down or unreachable (connection refused/timeout); invalid RAGFlow API key in env config; datasetId passed by caller does not exist so RAGFlow returns an unexpected payload; a newer RAGFlow server version changed the /retrieval response shape; DNS or proxy misconfiguration in the deployment.","solutions":["Check RAGFlow service health and connectivity from the knowledge service (curl RAGFLOW_BASE_URL /api/v1/retrieval or the configured endpoint).","Verify RAGFlow credentials/env vars (API key, base URL) used by ragflow_client are correct for the deployment.","Confirm the datasetId(s) passed to query() exist in RAGFlow; invalid ids surface here when the client raises instead of returning code!=0.","Read the chained cause in logs ('RAGFlow query exception: %s' plus 'from e') and fix the underlying exception class.","If the cause is a response-shape mismatch, verify the pinned RAGFlow image version matches what ragflow_client expects."],"exampleFix":"// before: generic call with no error introspection\nresult = await strategy.query(\"what is foo\", **{\"datasetId\": ds_id})\n\n// after: validate dataset and inputs, and catch the typed error\nfrom knowledge.exceptions.exception import ThirdPartyException\nif not ds_id or not isinstance(ds_id, str):\n    raise ValueError(\"datasetId must be a non-empty string\")\ntry:\n    result = await strategy.query(\"what is foo\", **{\"datasetId\": ds_id})\nexcept ThirdPartyException as e:\n    logger.exception(\"RAGFlow retrieval failed: %s\", e)\n    result = {\"query\": \"what is foo\", \"count\": 0, \"results\": []}","handlingStrategy":"try-catch","validationCode":"# before calling query()\nif not isinstance(query, str) or not query.strip():\n    raise ValueError(\"query must be a non-empty string\")\nds_id = kwargs.get(\"datasetId\")\nif ds_id is not None and not isinstance(ds_id, str):\n    raise TypeError(\"datasetId must be a string\")","typeGuard":"def has_valid_dataset(kwargs: dict) -> bool:\n    ds = kwargs.get(\"datasetId\")\n    return ds is None or (isinstance(ds, str) and bool(ds.strip()))","tryCatchPattern":"try:\n    result = await strategy.query(q, **{\"datasetId\": ds_id})\nexcept ThirdPartyException as e:\n    logger.exception(\"RAGFlow query failed: %s\", e)\n    result = {\"query\": q, \"count\": 0, \"results\": []}  # graceful degradation","preventionTips":["Health-check the RAGFlow endpoint before issuing queries in batch jobs.","Pin and test against the exact RAGFlow server version the client expects.","Keep RAGFlow API key/base URL in validated env config, checked at startup.","Always log the chained exception (raise ... from e) to preserve root cause."],"tags":["rag","ragflow","retrieval","third-party","network"],"backgroundTag":"upstream-api-error","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}