{"record":{"id":"3c18b6dd5799316f","repo":"iflytek/astron-agent","slug":"document-splitting-failed-after-retries","errorCode":null,"errorMessage":"Document splitting failed after retries","messagePattern":"Document splitting failed after retries","errorType":"exception","errorClass":"ThirdPartyException","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/xinghuo/xinghuo.py","lineNumber":142,"sourceCode":"    while retry_count < max_retries:\n        try:\n            response = await async_request(\n                post_body,\n                os.getenv(\"XINGHUO_RAG_URL\", \"\") + \"openapi/v1/file/split\",\n                **kwargs,\n            )\n            data = response\n            break\n        except Exception:\n            print(\n                f\"Retry {retry_count + 1}, document splitting not successful, continuing to retry...\"\n            )\n            retry_count += 1\n            if retry_count < max_retries:\n                await asyncio.sleep(1)\n\n    if data is None:\n        raise ThirdPartyException(\"Document splitting failed after retries\")\n\n    return data\n\n\nasync def get_chunks(\n    file_id: Optional[str] = None, **kwargs: Any\n) -> List[Dict[str, Any]]:\n    \"\"\"\n    Get document chunk content.\n\n    Args:\n        file_id: File ID\n\n    Returns:\n        List of document chunk content\n\n    Raises:\n        ThirdPartyException: Raised when document splitting fails","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/xinghuo/xinghuo.py#L124-L160","documentation":"The split() helper in the Xinghuo RAG client calls the remote document-splitting endpoint (openapi/v1/file/split) up to 3 times. If every attempt raises (via async_request) or the response is unusable, `data` stays None and this ThirdPartyException is thrown. It means the third-party Xinghuo knowledge-base service never returned a successful split result, not a local bug in your code.","triggerScenarios":"Calling split() when: the Xinghuo RAG endpoint returns code != 0 (raises ThirdPartyException from async_request, caught by the bare `except Exception`), aiohttp network errors or timeouts occur on all 3 attempts, XINGHUO_RAG_URL is unset/wrong (empty base URL), or credentials (assemble_spark_auth_headers) are invalid so the API rejects every request.","commonSituations":"XINGHUO_RAG_URL environment variable missing or pointing to a dead host; Xinghuo credentials expired; the remote service is down or overloaded; uploading a file format the splitter rejects; network egress blocked in a container/cluster so all 3 retries (~2s total) fail within seconds.","solutions":["Verify XINGHUO_RAG_URL is set and reachable (curl the host) and that Xinghuo auth headers/credentials are valid.","Hit the split endpoint manually with the same body to see the underlying desc from async_request — fix that root cause first (bad file, unsupported format, API error).","Check network egress/DNS from the deployment environment; the 3 retries with 1s sleep expire in ~2s, so transient outages easily exhaust them.","If transient upstream flakiness is common, increase max_retries or backoff in split(), or re-run the ingestion job later."],"exampleFix":"# before\nresponse = await async_request(post_body, os.getenv(\"XINGHUO_RAG_URL\", \"\") + \"openapi/v1/file/split\", **kwargs)\n# after\nbase = os.getenv(\"XINGHUO_RAG_URL\")\nif not base:\n    raise ValueError(\"XINGHUO_RAG_URL is not configured\")\nresponse = await async_request(post_body, base + \"openapi/v1/file/split\", **kwargs)","handlingStrategy":"try-catch","validationCode":"base = os.getenv(\"XINGHUO_RAG_URL\")\nif not base:\n    raise RuntimeError(\"XINGHUO_RAG_URL must be set before splitting documents\")\n# optionally pre-check reachability:\n# await aiohttp.ClientSession().head(base)","typeGuard":"def has_file_id(result: dict | None) -> bool:\n    return isinstance(result, dict) and bool(result.get(\"fileId\"))","tryCatchPattern":"try:\n    data = await split(document)\nexcept ThirdPartyException as e:\n    logger.error(\"Xinghuo split failed: %s\", e)\n    raise DocumentIngestionError(str(e)) from e","preventionTips":["Assert XINGHUO_RAG_URL and credentials are configured at service startup, not per-request.","Wrap split() in your own retry/backoff for transient upstream faults.","Validate file format and size before uploading to avoid remote split failures."],"tags":["third-party","rag","document-splitting","retry-exhausted","network"],"backgroundTag":"upstream-api-error","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"}