iflytek/astron-agent · error · ThirdPartyException

RAGFLOW_RAGError

RAGFLOW_RAGError

Error message

RAGFlow retrieval failed: {e}

What it means

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.

Solutions

1. Check RAGFlow service health and connectivity from the knowledge service (curl RAGFLOW_BASE_URL /api/v1/retrieval or the configured endpoint).
2. Verify RAGFlow credentials/env vars (API key, base URL) used by ragflow_client are correct for the deployment.
3. Confirm the datasetId(s) passed to query() exist in RAGFlow; invalid ids surface here when the client raises instead of returning code!=0.
4. Read the chained cause in logs ('RAGFlow query exception: %s' plus 'from e') and fix the underlying exception class.
5. If the cause is a response-shape mismatch, verify the pinned RAGFlow image version matches what ragflow_client expects.

Example fix

// before: generic call with no error introspection
result = await strategy.query("what is foo", **{"datasetId": ds_id})

// after: validate dataset and inputs, and catch the typed error
from knowledge.exceptions.exception import ThirdPartyException
if not ds_id or not isinstance(ds_id, str):
    raise ValueError("datasetId must be a non-empty string")
try:
    result = await strategy.query("what is foo", **{"datasetId": ds_id})
except ThirdPartyException as e:
    logger.exception("RAGFlow retrieval failed: %s", e)
    result = {"query": "what is foo", "count": 0, "results": []}

# before calling query()
if not isinstance(query, str) or not query.strip():
    raise ValueError("query must be a non-empty string")
ds_id = kwargs.get("datasetId")
if ds_id is not None and not isinstance(ds_id, str):
    raise TypeError("datasetId must be a string")

def has_valid_dataset(kwargs: dict) -> bool:
    ds = kwargs.get("datasetId")
    return ds is None or (isinstance(ds, str) and bool(ds.strip()))

try:
    result = await strategy.query(q, **{"datasetId": ds_id})
except ThirdPartyException as e:
    logger.exception("RAGFlow query failed: %s", e)
    result = {"query": q, "count": 0, "results": []}  # graceful degradation

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Document splitting failed after retries
• Failed to 【XINGHUO-RAG】; code
• REPO_STATUS_ILLEGAL
• RAGFLOW_RAGError
• Document splitting failed

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/39a7348e54c658f0. Report an issue: GitHub.

Appendix: source

Thrown at core/knowledge/service/impl/ragflow_strategy.py:83

                doc_ids=doc_ids,
                top_k=effective_top_k,
                threshold=threshold or 0,
                ext=ext,
            )
            return await self._execute_retrieval(
                payload=payload,
                query=query,
                threshold=threshold or 0,
                effective_top_k=effective_top_k,
            )

        except CustomException:
            raise
        except ThirdPartyException:
            raise
        except Exception as e:
            logger.error("RAGFlow query exception: %s", e)
            raise ThirdPartyException(
                msg=f"RAGFlow retrieval failed: {e}",
                e=CodeEnum.RAGFLOW_RAGError,
            ) from e

    async def _resolve_query_datasets(
        self, dataset_ids: Optional[List[str]]
    ) -> List[str]:
        """Return requested dataset ids or the default dataset id."""
        if not dataset_ids:
            default_name = RagflowUtils.get_default_dataset_name()
            ds_id = await RagflowUtils.ensure_dataset(default_name)
            return [ds_id] if ds_id else []
        return list(dataset_ids)

    async def _resolve_dataset_id(
        self,
        dataset_id_input: Optional[str],
        group: Optional[str] = None,

View on GitHub (pinned to 5e758547a8)