{"record":{"id":"c257c2858f895a3f","repo":"iflytek/astron-agent","slug":"ragflow-document-disappeared-before-chunk-retrieval-doc-doc","errorCode":null,"errorMessage":"RAGFlow document disappeared before chunk retrieval: doc={doc_id}","messagePattern":"RAGFlow document disappeared before chunk retrieval: doc=(.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/ragflow/ragflow_utils.py","lineNumber":371,"sourceCode":"        being misreported as a valid empty document.\n\n        Args:\n            dataset_id: Dataset ID\n            doc_id: Document ID\n            max_retries: Maximum incomplete-snapshot retries (default: 15)\n            retry_delay: Delay between retries in seconds (default: 3.0)\n\n        Returns:\n            Complete chunk list, or an empty list after all empty retries.\n        \"\"\"\n        if max_retries < 0:\n            raise ValueError(\"max_retries must be non-negative\")\n        if retry_delay < 0:\n            raise ValueError(\"retry_delay must be non-negative\")\n\n        doc_info = await get_document_info(dataset_id, doc_id)\n        if doc_info is None:\n            raise RuntimeError(\n                f\"RAGFlow document disappeared before chunk retrieval: doc={doc_id}\"\n            )\n\n        expected_count = RagflowUtils._normalize_expected_chunk_count(\n            doc_info.get(\"chunk_count\")\n        )\n\n        last_visible_count = 0\n        last_chunk_ids: Optional[tuple[str, ...]] = None\n        stable_partial_reads = 0\n        for attempt in range(max_retries + 1):\n            chunks = await fetch_all_document_chunks(dataset_id, doc_id, page_size=100)\n            last_visible_count = len(chunks)\n            has_complete_snapshot = (\n                expected_count is not None and last_visible_count >= expected_count\n            )\n            if has_complete_snapshot:\n                logger.info(","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/ragflow/ragflow_utils.py#L353-L389","documentation":"get_document_chunks first fetches document metadata via get_document_info; if that returns None the document no longer exists (or is not visible) in the RAGFlow dataset, and this RuntimeError is raised before any chunk polling begins. It prevents polling for chunks of a phantom document.","triggerScenarios":"Calling get_document_chunks with a doc_id that was deleted, that never existed, that belongs to a different dataset_id, or while RAGFlow returns 404/empty for the document lookup.","commonSituations":"Chunk retrieval racing with document deletion; stale doc ids cached in the application database; wrong dataset_id paired with a valid doc_id; RAGFlow data reset/reseeded between environments.","solutions":["Verify the doc_id/dataset_id pair exists via the RAGFlow API or its UI before fetching chunks","Handle deletion events so consumers stop querying removed documents","Check that the application is pointed at the intended RAGFlow instance/environment (no data drift)","Refresh stale document references stored in your own DB from RAGFlow's list-documents endpoint"],"exampleFix":"// before\nchunks = await get_document_chunks(ds_id, cached_doc_id)\n// after\ndocs = await ragflow.list_documents(ds_id)\nif cached_doc_id not in {d['id'] for d in docs}:\n    return []\nchunks = await get_document_chunks(ds_id, cached_doc_id)","handlingStrategy":"try-catch","validationCode":"doc = await get_document_info(dataset_id, doc_id)\nif doc is None:\n    raise EntityGoneError(f\"doc {doc_id} missing from dataset {dataset_id}\")","typeGuard":"def document_exists(doc: dict | None) -> bool:\n    return isinstance(doc, dict) and bool(doc.get(\"id\"))","tryCatchPattern":"try:\n    chunks = await get_document_chunks(ds, doc_id)\nexcept RuntimeError as e:\n    if \"disappeared before chunk retrieval\" in str(e):\n        logger.warning(\"doc %s gone; refreshing index\", doc_id)\n        await refresh_document_index(ds)\n        return []\n    raise","preventionTips":["Listen for deletion events and purge stale doc ids from your DB","Always store (dataset_id, doc_id) pairs together, never ids alone","Verify doc ids after environment/data migrations","Re-check existence before long-running pipelines that use cached ids"],"tags":["ragflow","not-found","document-lifecycle"],"backgroundTag":"entity-not-found","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}