{"record":{"id":"5c5bad1135a18020","repo":"iflytek/astron-agent","slug":"ragflow-ragerror","errorCode":"RAGFLOW_RAGError","errorMessage":"RAGFlow get_document_info doc={doc_id} dataset={dataset_id}: code={code} message={msg}","messagePattern":"RAGFlow get_document_info doc=(.+?) dataset=(.+?): code=(.+?) message=(.+?)","errorType":"error_code","errorClass":"ThirdPartyException","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/ragflow/ragflow_client.py","lineNumber":792,"sourceCode":"        logger.warning(f\"empty doc_id for dataset={dataset_id}\")\n        return None\n    response = await list_documents_in_dataset(\n        dataset_id, doc_id=doc_id, page=1, page_size=1\n    )\n    code = response.get(\"code\")\n    if code == 0:\n        data = response.get(\"data\") or {}\n        docs = data.get(\"docs\") or []\n        # page_size=1 + server-side exact-match filter => at most one doc;\n        # the id re-check is defensive in case a future RAGFlow release\n        # relaxes the filter to LIKE.\n        if docs and docs[0].get(\"id\") == doc_id:\n            return docs[0]\n        return None\n    if code == _RAGFLOW_DATA_ERROR:\n        return None\n    msg = response.get(\"message\", \"Unknown error\")\n    raise ThirdPartyException(\n        msg=(\n            f\"RAGFlow get_document_info doc={doc_id} dataset={dataset_id}: \"\n            f\"code={code} message={msg}\"\n        ),\n        e=CodeEnum.RAGFLOW_RAGError,\n    )\n\n\nasync def delete_documents(dataset_id: str, document_ids: List[str]) -> Dict[str, Any]:\n    \"\"\"\n    Delete documents API\n\n    Args:\n        dataset_id: Dataset ID\n        document_ids: List of document IDs to delete\n\n    Returns:\n        Deletion response","sourceCodeStart":774,"sourceCodeEnd":810,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/ragflow/ragflow_client.py#L774-L810","documentation":"get_document_info raises ThirdPartyException with CodeEnum.RAGFLOW_RAGError when the RAGFlow API returns an unrecognized non-success code (not the data-error code that maps to None). It wraps the server code and message for diagnosis.","triggerScenarios":"GET document info returns an unexpected error code: internal RAGFlow error, permission denied for the dataset, invalid dataset/document id combination the server rejects with a non-data-error code, or server-side outage.","commonSituations":"Parsing-status polling (_query_document_parsing_status) hitting a RAGFlow that is restarting or degraded; dataset ids from another tenant; API key revoked mid-operation.","solutions":["Read the wrapped code/message to identify the RAGFlow-side failure; check RAGFlow server logs for that request.","Validate dataset_id/doc_id and that the API key's tenant owns the dataset.","Handle ThirdPartyException at the polling layer so status polling degrades gracefully (retry/abort) instead of crashing the pipeline.","Retry with backoff for transient server errors (5xx-class codes)."],"exampleFix":"// before\ninfo = await client.get_document_info(ds, doc)  // throws on transient error\n// after\ntry { info = await client.get_document_info(ds, doc); }\ncatch (e) {\n  logger.warn(\"transient get_document_info failure, will retry\", e);\n  await sleep(backoff++);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    info = await get_document_info(dataset_id, document_id)\nexcept ThirdPartyException as e:\n    logger.warning(f\"RAGFlow document info unavailable: {e}\")\n    # degrade: mark status unknown and let polling retry\n    info = None","preventionTips":["Keep RAGFlow server healthy/monitored; this error surfaces upstream degradation","Validate ids and tenant ownership before calling","Use bounded retries with backoff for transient codes in polling loops"],"tags":["ragflow","third-party","api-error"],"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"}