{"record":{"id":"e5d6bad47d31fe1d","repo":"iflytek/astron-agent","slug":"poll-interval-must-be-greater-than-0","errorCode":null,"errorMessage":"poll_interval must be greater than 0","messagePattern":"poll_interval must be greater than 0","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/ragflow/ragflow_client.py","lineNumber":959,"sourceCode":"\n\ndef _format_parsing_snapshot(snapshot: Dict[str, Any]) -> str:\n    \"\"\"Format a compact status description for logs and propagated errors.\"\"\"\n    return (\n        f\"status={snapshot['status']}, progress={snapshot['progress']}, \"\n        f\"chunks={snapshot['chunk_count']}, tokens={snapshot['token_count']}, \"\n        f\"message={snapshot['progress_msg'] or '-'}\"\n    )\n\n\ndef _validate_parsing_wait_parameters(\n    max_wait_time: int, poll_interval: float, max_status_errors: int\n) -> None:\n    \"\"\"Reject polling configurations that cannot make forward progress.\"\"\"\n    if max_wait_time <= 0:\n        raise ValueError(\"max_wait_time must be greater than 0\")\n    if poll_interval <= 0:\n        raise ValueError(\"poll_interval must be greater than 0\")\n    if max_status_errors <= 0:\n        raise ValueError(\"max_status_errors must be greater than 0\")\n\n\nasync def _query_document_parsing_status(\n    dataset_id: str, doc_id: str\n) -> tuple[Optional[Dict[str, Any]], Optional[Exception]]:\n    \"\"\"Return a document snapshot or the recoverable query error.\"\"\"\n    try:\n        return await get_document_info(dataset_id, doc_id), None\n    except Exception as error:\n        return None, error\n\n\ndef _handle_parsing_status_error(\n    dataset_id: str,\n    doc_id: str,\n    error: Exception,","sourceCodeStart":941,"sourceCodeEnd":977,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/ragflow/ragflow_client.py#L941-L977","documentation":"_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.","triggerScenarios":"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).","commonSituations":"Config defaulting poll_interval to 0 for 'fastest'; env var producing empty string coerced oddly; copy-paste from another client that used milliseconds.","solutions":["Pass a positive poll_interval (e.g. 1.0–5.0 seconds) to wait_for_parsing.","Fix the configuration source; ensure units are seconds (float).","Validate all polling parameters at config load time to fail before any API call is made.","If sub-second polling is needed, use a small positive value like 0.5, never 0."],"exampleFix":"# before\nawait wait_for_parsing(ds, doc, max_wait_time=300, poll_interval=0)  # ValueError\n# after\nawait wait_for_parsing(ds, doc, max_wait_time=300, poll_interval=2.0)","handlingStrategy":"validation","validationCode":"assert poll_interval > 0, \"poll_interval must be a positive number of seconds\"","typeGuard":"def valid_interval(v) -> bool:\n    return isinstance(v, (int, float)) and v > 0","tryCatchPattern":"try:\n    await wait_for_parsing(ds, doc, poll_interval=poll_interval)\nexcept ValueError as e:\n    logger.error(f\"Invalid polling configuration: {e}\")\n    raise","preventionTips":["Keep poll_interval units (seconds) documented next to the config key","Clamp incoming values: poll_interval = max(poll_interval, 0.5)","Never configure 0/negative intervals to 'speed up' polling — it just hammers the API"],"tags":["ragflow","argument-validation","polling"],"backgroundTag":"invalid-argument-value","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}