iflytek/astron-agent · error · RuntimeError

RAGFlow chunk snapshot remained incomplete after retries…

Error message

RAGFlow chunk snapshot remained incomplete after retries: doc={doc_id}, visible={last_visible_count}, expected={expected_count}

What it means

_finalize_chunk_retrieval raises this RuntimeError when, after exhausting max_retries polling RAGFlow, the number of visible chunks (last_visible_count) is still strictly less than the expected_count derived from the document's chunk_count. The document's chunk index is not yet fully committed/visible in RAGFlow, so a complete snapshot cannot be returned.

Solutions

Increase max_retries or retry_delay in the get_document_chunks call to give RAGFlow more time
Verify the document's parse/run status in RAGFlow is actually complete before fetching chunks
Re-run chunk retrieval later once indexing has settled (retry with backoff)
Check RAGFlow service health/logs for indexing backlogs or failures

Example fix

// before
chunks = await get_document_chunks(dataset_id, doc_id, max_retries=2, retry_delay=1.0)
// after
chunks = await get_document_chunks(dataset_id, doc_id, max_retries=10, retry_delay=3.0)

Defensive patterns

Strategy: retry

Validate before calling

doc = await get_document_info(dataset_id, doc_id)
if doc is None:
    raise RuntimeError(f"doc {doc_id} not found")
expected = doc.get("chunk_count") or 0
if expected == 0:
    raise RuntimeError(f"doc {doc_id} has no chunks to wait for")

Try / catch

try:
    chunks = await get_document_chunks(ds, doc_id, max_retries=10, retry_delay=3.0)
except RuntimeError as e:
    if "remained incomplete" in str(e):
        await asyncio.sleep(30)  # backoff, then retry whole retrieval
        chunks = await get_document_chunks(ds, doc_id, max_retries=10)
    else:
        raise

Prevention

Only fetch chunks after the document's parse status is fully complete
Budget generous max_retries/retry_delay for large documents
Add exponential backoff around whole chunk-retrieval calls
Monitor RAGFlow indexing lag to size retry budgets correctly

When it happens

Trigger: get_document_chunks is called immediately after a document finishes parsing while RAGFlow is still flushing chunks; expected_count > 0 and all polling attempts time out with fewer chunks visible.

Common situations: Right-after-upload race in bulk ingestion pipelines; RAGFlow indexing is slow under load; a small max_retries / short retry_delay budget in get_document_chunks; parse status reported done but index lagging.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

            expected_count = int(raw_count) if raw_count is not None else None
        except (TypeError, ValueError):
            return None
        if expected_count is not None and expected_count < 0:
            return None
        return expected_count

    @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,

View on GitHub (pinned to 5e758547a8)