What causes "max_retries must be non-negative" in iflytek/astron-agent?

Clamp the value before calling: max_retries = max(0, configured_retries)

iflytek/astron-agent · error · ValueError

max_retries must be non-negative

Error message

max_retries must be non-negative

What it means

get_document_chunks validates its retry parameters up front and raises ValueError when max_retries is negative. A negative retry count is meaningless — it would mean performing fewer than zero polling attempts — so the function fails fast rather than silently skipping polling.

Solutions

Clamp the value before calling: max_retries = max(0, configured_retries)
Fix the computation that produced the negative retry budget
Validate config values at load time so negatives are rejected early
Pass the documented defaults (max_retries positive, retry_delay 3.0) instead of hand-rolled values

Example fix

// before
chunks = await get_document_chunks(ds, doc_id, max_retries=remaining)
// after
chunks = await get_document_chunks(ds, doc_id, max_retries=max(0, remaining))

Defensive patterns

Strategy: validation

Validate before calling

def safe_max_retries(v) -> int:
    n = int(v) if v is not None else 3
    if n < 0:
        raise ValueError("max_retries must be >= 0")
    return n

chunks = await get_document_chunks(ds, doc_id, max_retries=safe_max_retries(cfg_retries))

Type guard

def is_valid_max_retries(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 0

Try / catch

try:
    chunks = await get_document_chunks(ds, doc_id, max_retries=n)
except ValueError as e:
    logger.error("bad retry config: %s", e)
    chunks = await get_document_chunks(ds, doc_id)  # fall back to defaults

Prevention

Clamp computed retry budgets with max(0, value)
Validate retry config at startup, not at call time
Avoid deriving counts by raw subtraction that can go negative
Use constants/defaults instead of ad-hoc inline values

When it happens

Trigger: Calling get_document_chunks(dataset_id, doc_id, max_retries=-1) (or any negative value), typically from miscomputed config such as retries = limit - used when used > limit.

Common situations: Retry budget computed by subtraction going negative; env/config loaded as a negative number; off-by-one sign errors in wrappers around get_document_chunks.

Related errors

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

Appendix: source

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

    ) -> List[Dict[str, Any]]:
        """
        Get all chunks after parsing, retrying incomplete search snapshots.

        Each attempt delegates to the canonical fail-closed paginator. RAGFlow
        API errors and incomplete pagination therefore propagate instead of
        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)

View on GitHub (pinned to 5e758547a8)