iflytek/astron-agent · error · RuntimeError

fetch_all_document_chunks failed on page

Error message

fetch_all_document_chunks failed on page {page} for doc={document_id}: code={resp.get('code')}, message={resp.get('message')}

What it means

fetch_all_document_chunks aborts when a page request to list document chunks returns a RAGFlow error code != 0. The error propagates the server's code and message so the caller knows pagination failed mid-way.

Solutions

Validate dataset_id and document_id exist and belong to the tenant of the API key before paginating.
Retry the whole fetch (not per-page) with backoff if the failure is transient (5xx / server load).
Check RAGFlow server logs for the corresponding error code and message.
Refresh/regenerate the RAGFlow API key if the code indicates an auth problem.

Example fix

# before: one long fetch, fails whole call
chunks = await fetch_all_document_chunks(dataset_id, doc_id)
# after: bounded retry on transient failure
for attempt in range(3):
    try:
        chunks = await fetch_all_document_chunks(dataset_id, doc_id)
        break
    except RuntimeError as e:
        if attempt == 2:
            raise
        await asyncio.sleep(2 ** attempt)

Defensive patterns

Strategy: retry

Try / catch

try:
    chunks = await fetch_all_document_chunks(dataset_id, document_id)
except RuntimeError as e:
    if "failed on page" in str(e):
        logger.warning(f"Transient chunk-page failure, retrying: {e}")
        await asyncio.sleep(2)
        chunks = await fetch_all_document_chunks(dataset_id, document_id)
    else:
        raise

Prevention

Validate dataset_id/document_id and ownership before paginating
Apply bounded retries at the whole-fetch level, not per page
Monitor RAGFlow server health; alert on repeated non-zero codes

When it happens

Trigger: RAGFlow returning code!=0 on GET /api/v1/datasets/{id}/documents/{doc_id}/chunks for any page: invalid dataset_id/document_id, expired/invalid API key, server-side error, or chunk index invalidated mid-pagination.

Common situations: Document deleted while paginating; dataset id typo'd or from a different tenant; RAGFlow server under load returning 5xx mapped into code; token/permission problems surfacing only on this endpoint.

Related errors

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

Appendix: source

Thrown at core/knowledge/infra/ragflow/ragflow_client.py:715

            chunk count.

    Returns:
        All chunks flattened into a single list (possibly empty).

    Raises:
        RuntimeError: on non-zero ``code`` from any paginated call, or when
            ``max_pages`` is exceeded without ``total`` being reached.
    """
    chunks: List[Dict[str, Any]] = []
    # Optional so a page that drops ``total`` can't downgrade the stop condition.
    total: Optional[int] = None
    page = 1
    while page <= max_pages:
        resp = await list_document_chunks(
            dataset_id, document_id, page=page, page_size=page_size
        )
        if resp.get("code") != 0:
            raise RuntimeError(
                f"fetch_all_document_chunks failed on page {page} for "
                f"doc={document_id}: code={resp.get('code')}, "
                f"message={resp.get('message')}"
            )
        data = resp.get("data") or {}
        batch = data.get("chunks") or []
        chunks.extend(batch)
        # Missing/None/non-int => keep last-known good value.
        raw_total = data.get("total")
        if isinstance(raw_total, int) and raw_total >= 0:
            total = raw_total
        if total is not None and len(chunks) >= total:
            return chunks
        if not batch:
            # Protocol anomaly (stale pagination, mid-request deletion, or
            # server mis-report): fail closed to avoid re-inserting the
            # missing chunks as if they didn't exist.
            raise RuntimeError(

View on GitHub (pinned to 5e758547a8)