iflytek/astron-agent · error · RuntimeError

RAGFlow document disappeared before chunk retrieval: doc=

Error message

RAGFlow document disappeared before chunk retrieval: doc={doc_id}

What it means

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.

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

Example fix

// before
chunks = await get_document_chunks(ds_id, cached_doc_id)
// after
docs = await ragflow.list_documents(ds_id)
if cached_doc_id not in {d['id'] for d in docs}:
    return []
chunks = await get_document_chunks(ds_id, cached_doc_id)

Defensive patterns

Strategy: try-catch

Validate before calling

doc = await get_document_info(dataset_id, doc_id)
if doc is None:
    raise EntityGoneError(f"doc {doc_id} missing from dataset {dataset_id}")

Type guard

def document_exists(doc: dict | None) -> bool:
    return isinstance(doc, dict) and bool(doc.get("id"))

Try / catch

try:
    chunks = await get_document_chunks(ds, doc_id)
except RuntimeError as e:
    if "disappeared before chunk retrieval" in str(e):
        logger.warning("doc %s gone; refreshing index", doc_id)
        await refresh_document_index(ds)
        return []
    raise

Prevention

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

When it happens

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

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

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at core/knowledge/infra/ragflow/ragflow_utils.py:371

        being misreported as a valid empty document.

        Args:
            dataset_id: Dataset ID
            doc_id: Document ID
            max_retries: Maximum incomplete-snapshot retries (default: 15)
            retry_delay: Delay between retries in seconds (default: 3.0)

        Returns:
            Complete chunk list, or an empty list after all empty retries.
        """
        if max_retries < 0:
            raise ValueError("max_retries must be non-negative")
        if retry_delay < 0:
            raise ValueError("retry_delay must be non-negative")

        doc_info = await get_document_info(dataset_id, doc_id)
        if doc_info is None:
            raise RuntimeError(
                f"RAGFlow document disappeared before chunk retrieval: doc={doc_id}"
            )

        expected_count = RagflowUtils._normalize_expected_chunk_count(
            doc_info.get("chunk_count")
        )

        last_visible_count = 0
        last_chunk_ids: Optional[tuple[str, ...]] = None
        stable_partial_reads = 0
        for attempt in range(max_retries + 1):
            chunks = await fetch_all_document_chunks(dataset_id, doc_id, page_size=100)
            last_visible_count = len(chunks)
            has_complete_snapshot = (
                expected_count is not None and last_visible_count >= expected_count
            )
            if has_complete_snapshot:
                logger.info(

View on GitHub (pinned to 5e758547a8)