iflytek/astron-agent · error · ValueError

poll_interval must be greater than 0

Error message

poll_interval must be greater than 0

What it means

_validate_parsing_wait_parameters rejects poll_interval <= 0 because a zero/negative interval would busy-loop the status endpoint with no delay, hammering the RAGFlow server. Same upfront validation family as max_wait_time.

Solutions

1. Pass a positive poll_interval (e.g. 1.0–5.0 seconds) to wait_for_parsing.
2. Fix the configuration source; ensure units are seconds (float).
3. Validate all polling parameters at config load time to fail before any API call is made.
4. If sub-second polling is needed, use a small positive value like 0.5, never 0.

Example fix

# before
await wait_for_parsing(ds, doc, max_wait_time=300, poll_interval=0)  # ValueError
# after
await wait_for_parsing(ds, doc, max_wait_time=300, poll_interval=2.0)

assert poll_interval > 0, "poll_interval must be a positive number of seconds"

def valid_interval(v) -> bool:
    return isinstance(v, (int, float)) and v > 0

try:
    await wait_for_parsing(ds, doc, poll_interval=poll_interval)
except ValueError as e:
    logger.error(f"Invalid polling configuration: {e}")
    raise

When it happens

Trigger: wait_for_parsing called with poll_interval=0 or negative from a bad config, float parsing failure, or unit confusion (milliseconds passed where seconds are expected, e.g. 500 meaning 500s intended as 500ms is fine but -1 or 0 is not).

Common situations: Config defaulting poll_interval to 0 for 'fastest'; env var producing empty string coerced oddly; copy-paste from another client that used milliseconds.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• max_wait_time must be greater than 0
• All retry attempts failed
• API request failed
• Cannot provide both fileUrl and file parameters
• ChunkDeleteFailed

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

Appendix: source

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

def _format_parsing_snapshot(snapshot: Dict[str, Any]) -> str:
    """Format a compact status description for logs and propagated errors."""
    return (
        f"status={snapshot['status']}, progress={snapshot['progress']}, "
        f"chunks={snapshot['chunk_count']}, tokens={snapshot['token_count']}, "
        f"message={snapshot['progress_msg'] or '-'}"
    )


def _validate_parsing_wait_parameters(
    max_wait_time: int, poll_interval: float, max_status_errors: int
) -> None:
    """Reject polling configurations that cannot make forward progress."""
    if max_wait_time <= 0:
        raise ValueError("max_wait_time must be greater than 0")
    if poll_interval <= 0:
        raise ValueError("poll_interval must be greater than 0")
    if max_status_errors <= 0:
        raise ValueError("max_status_errors must be greater than 0")


async def _query_document_parsing_status(
    dataset_id: str, doc_id: str
) -> tuple[Optional[Dict[str, Any]], Optional[Exception]]:
    """Return a document snapshot or the recoverable query error."""
    try:
        return await get_document_info(dataset_id, doc_id), None
    except Exception as error:
        return None, error


def _handle_parsing_status_error(
    dataset_id: str,
    doc_id: str,
    error: Exception,

View on GitHub (pinned to 5e758547a8)