{"record":{"id":"202e51c75d569360","repo":"iflytek/astron-agent","slug":"retry-delay-must-be-non-negative","errorCode":null,"errorMessage":"retry_delay must be non-negative","messagePattern":"retry_delay must be non-negative","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/ragflow/ragflow_utils.py","lineNumber":367,"sourceCode":"        Get all chunks after parsing, retrying incomplete search snapshots.\n\n        Each attempt delegates to the canonical fail-closed paginator. RAGFlow\n        API errors and incomplete pagination therefore propagate instead of\n        being misreported as a valid empty document.\n\n        Args:\n            dataset_id: Dataset ID\n            doc_id: Document ID\n            max_retries: Maximum incomplete-snapshot retries (default: 15)\n            retry_delay: Delay between retries in seconds (default: 3.0)\n\n        Returns:\n            Complete chunk list, or an empty list after all empty retries.\n        \"\"\"\n        if max_retries < 0:\n            raise ValueError(\"max_retries must be non-negative\")\n        if retry_delay < 0:\n            raise ValueError(\"retry_delay must be non-negative\")\n\n        doc_info = await get_document_info(dataset_id, doc_id)\n        if doc_info is None:\n            raise RuntimeError(\n                f\"RAGFlow document disappeared before chunk retrieval: doc={doc_id}\"\n            )\n\n        expected_count = RagflowUtils._normalize_expected_chunk_count(\n            doc_info.get(\"chunk_count\")\n        )\n\n        last_visible_count = 0\n        last_chunk_ids: Optional[tuple[str, ...]] = None\n        stable_partial_reads = 0\n        for attempt in range(max_retries + 1):\n            chunks = await fetch_all_document_chunks(dataset_id, doc_id, page_size=100)\n            last_visible_count = len(chunks)\n            has_complete_snapshot = (","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/ragflow/ragflow_utils.py#L349-L385","documentation":"get_document_chunks validates retry_delay and raises ValueError when it is negative. A negative inter-poll delay is nonsensical (it would mean sleeping backwards), so the function rejects it immediately alongside the max_retries check.","triggerScenarios":"Calling get_document_chunks(dataset_id, doc_id, retry_delay=-1.0) or any negative float, usually from miscomputed backoff arithmetic (e.g. delay = base * factor with a negative factor) or bad config.","commonSituations":"Backoff formulas with negative multipliers; config/env values entered as negative numbers; wiring an elapsed-time delta (which can be negative) into retry_delay.","solutions":["Clamp before calling: retry_delay = max(0.0, computed_delay)","Fix the backoff/config computation yielding the negative delay","Validate timing config at startup and reject negatives","Use the documented default retry_delay of 3.0 seconds"],"exampleFix":"// before\nchunks = await get_document_chunks(ds, doc_id, retry_delay=backoff)\n// after\nchunks = await get_document_chunks(ds, doc_id, retry_delay=max(0.0, backoff))","handlingStrategy":"validation","validationCode":"def safe_retry_delay(v) -> float:\n    d = float(v) if v is not None else 3.0\n    if d < 0:\n        raise ValueError(\"retry_delay must be >= 0\")\n    return d\n\nchunks = await get_document_chunks(ds, doc_id, retry_delay=safe_retry_delay(cfg_delay))","typeGuard":"def is_valid_retry_delay(v) -> bool:\n    return isinstance(v, (int, float)) and not isinstance(v, bool) and v >= 0","tryCatchPattern":"try:\n    chunks = await get_document_chunks(ds, doc_id, retry_delay=d)\nexcept ValueError as e:\n    logger.error(\"bad retry_delay: %s\", e)\n    chunks = await get_document_chunks(ds, doc_id)  # default 3.0","preventionTips":["Clamp backoff computations with max(0.0, value)","Check sign of multipliers in backoff formulas","Validate timing-related config at load time","Prefer documented defaults over computed delays when unsure"],"tags":["validation","arguments","ragflow"],"backgroundTag":"argument-out-of-range","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}