{"record":{"id":"09ef927613c06a4d","repo":"iflytek/astron-agent","slug":"chunksavefailed","errorCode":"ChunkSaveFailed","errorMessage":"Unable to resolve RAGFlow dataset","messagePattern":"Unable to resolve RAGFlow dataset","errorType":"error_code","errorClass":"CustomException","httpStatus":null,"severity":"error","filePath":"core/knowledge/service/impl/ragflow_strategy.py","lineNumber":489,"sourceCode":"            \"chunkType\": \"RAW\",\n            \"content\": content,\n            \"question\": None,\n            \"answer\": None,\n            \"dataIndex\": error_id,\n            \"imgReference\": None,\n            \"copiedFrom\": None,\n        }\n\n    async def _validate_chunks_save_config(\n        self,\n        doc_id: str,\n        dataset_id: Optional[str] = None,\n    ) -> str:\n        \"\"\"Resolve dataset for chunks_save.\"\"\"\n        resolved = await self._resolve_dataset_id(dataset_id)\n        if not resolved:\n            logger.error(\"Unable to resolve RAGFlow dataset for chunks_save\")\n            raise CustomException(\n                CodeEnum.ChunkSaveFailed,\n                \"Unable to resolve RAGFlow dataset\",\n            )\n        return resolved\n\n    async def _validate_document_exists(self, dataset_id: str, doc_id: str) -> None:\n        \"\"\"Validate that the document exists in RAGFlow.\n\n        Delegates to ``ragflow_client.get_document_info`` which uses RAGFlow's\n        server-side ``id`` filter for an O(1) exact lookup (verified against\n        v0.20.5 ~ v0.24.0). Raises ``CustomException(ChunkSaveFailed)`` on\n        not-found or on any underlying error.\n\n        ``get_document_info`` returns ``None`` only for the server's\n        ``DATA_ERROR`` (code=102) \"not owned / not found\" path, raises\n        ``ThirdPartyException`` for other non-zero codes, and lets transport\n        errors propagate. The generic ``except Exception`` branch below wraps\n        all raised errors into ``CustomException(ChunkSaveFailed)`` so the","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/service/impl/ragflow_strategy.py#L471-L507","documentation":"chunks_save could not determine which RAGFlow dataset the target document belongs to. The strategy resolves dataset_id from the caller-provided value or a fallback (e.g. config/knowledge-base mapping); when _resolve_dataset_id returns None there is no dataset to address the RAGFlow API, so the save is aborted with ChunkSaveFailed.","triggerScenarios":"chunks_save called with dataset_id=None and no resolvable fallback; the knowledge base record backing the dataset mapping was deleted or never created; environment/config lacking the RAGFlow dataset identifier.","commonSituations":"Document ingested outside the platform so no dataset binding exists; RAGFlow tenant changed and the old dataset ID no longer exists; a config key for the default dataset was renamed or left empty after deployment.","solutions":["Pass an explicit, valid dataset_id to chunks_save instead of relying on resolution.","Verify the knowledge base -> RAGFlow dataset mapping exists (check the knowledge record in the DB and the RAGFlow API list-datasets).","Confirm RAGFlow config (API key/base URL/tenant) so _resolve_dataset_id can query the correct instance.","Re-create the dataset in RAGFlow and update the mapping if the dataset was deleted."],"exampleFix":"// before\nawait strategy.chunks_save(docId=\"doc123\", chunks=chunks)  # dataset_id=None\n// after\ndataset_id = await kb_service.get_ragflow_dataset_id(kb_id)\nassert dataset_id, \"knowledge base has no RAGFlow dataset\"\nawait strategy.chunks_save(docId=\"doc123\", chunks=chunks, dataset_id=dataset_id)","handlingStrategy":"validation","validationCode":"async def can_resolve_dataset(strategy, dataset_id):\n    return bool(await strategy._resolve_dataset_id(dataset_id))\n# call chunks_save only if can_resolve_dataset(...) is True","typeGuard":null,"tryCatchPattern":"try:\n    await strategy.chunks_save(docId=doc_id, chunks=chunks, dataset_id=dataset_id)\nexcept CustomException as e:\n    if \"Unable to resolve RAGFlow dataset\" in str(e):\n        handle_missing_dataset_binding(kb_id)\n    else:\n        raise","preventionTips":["Always store the RAGFlow dataset ID on the knowledge base record at ingestion time.","Alert on KB rows with empty dataset bindings.","Validate dataset existence after any RAGFlow migration."],"tags":["ragflow","dataset","configuration","chunks-save"],"backgroundTag":"resource-not-found","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"}