iflytek/astron-agent · error · RuntimeError

RAGFlow chunk snapshot did not stabilize after retries: doc=

Error message

RAGFlow chunk snapshot did not stabilize after retries: doc={doc_id}, visible={last_visible_count}, expected={expected_count}

What it means

_finalize_chunk_retrieval raises this RuntimeError when the visible chunk count is positive and greater than expected_count (or otherwise keeps changing) after retries — i.e. the snapshot did not stabilize. It signals RAGFlow was still actively modifying the chunk set (re-parsing, re-chunking) during polling, so any snapshot taken would be inconsistent.

Solutions

Stop concurrent parse/re-parse jobs on the document before fetching its chunks
Serialize ingestion: only call get_document_chunks after the parse job fully completes
Increase max_retries/retry_delay to outlast background re-indexing
Check for duplicate ingestion pipelines writing to the same RAGFlow document

Example fix

// before
await reparse(doc_id)
chunks = await get_document_chunks(ds, doc_id)
// after
await reparse_and_wait_until_done(doc_id)
chunks = await get_document_chunks(ds, doc_id, max_retries=10)

Defensive patterns

Strategy: retry

Validate before calling

# ensure no parse job is running for this doc before reading
status = await get_document_run_status(ds, doc_id)
if status not in ("DONE", None):
    raise RuntimeError(f"doc {doc_id} is being modified (status={status}); retry later")

Try / catch

try:
    chunks = await get_document_chunks(ds, doc_id)
except RuntimeError as e:
    if "did not stabilize" in str(e):
        schedule_retry(doc_id, delay_minutes=5)
        return None
    raise

Prevention

Never re-parse a document while consumers are reading its chunks
Serialize ingestion and read operations per document (lock or queue)
Debounce rapid re-upload/re-parse requests for the same doc
Alert on repeated instability — usually a sign of concurrent writers

When it happens

Trigger: Polling get_document_chunks while a document is being re-parsed or deleted-and-recreated; last_visible_count > 0 but never equals the expected snapshot size within the retry budget.

Common situations: Triggering a re-parse while a consumer reads chunks concurrently; RAGFlow background re-index jobs; two ingestion jobs racing on the same document id.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

    @staticmethod
    def _finalize_chunk_retrieval(
        dataset_id: str,
        doc_id: str,
        *,
        expected_count: Optional[int],
        last_visible_count: int,
        max_retries: int,
    ) -> List[Dict[str, Any]]:
        """Return an empty snapshot or raise the final incomplete-state error."""
        if expected_count is not None and expected_count > last_visible_count:
            raise RuntimeError(
                "RAGFlow chunk snapshot remained incomplete after retries: "
                f"doc={doc_id}, visible={last_visible_count}, "
                f"expected={expected_count}"
            )

        if last_visible_count > 0:
            raise RuntimeError(
                "RAGFlow chunk snapshot did not stabilize after retries: "
                f"doc={doc_id}, visible={last_visible_count}, "
                f"expected={expected_count}"
            )

        logger.warning(
            "RAGFlow document returned zero chunks after retries: "
            "dataset=%s doc=%s attempts=%d",
            dataset_id,
            doc_id,
            max_retries + 1,
        )
        return []

    @staticmethod
    async def get_document_chunks(
        dataset_id: str, doc_id: str, max_retries: int = 15, retry_delay: float = 3.0
    ) -> List[Dict[str, Any]]:

View on GitHub (pinned to 5e758547a8)