{"record":{"id":"19fd9323d29db7f5","repo":"iflytek/astron-agent","slug":"document-splitting-failed","errorCode":null,"errorMessage":"Document splitting failed","messagePattern":"Document splitting failed","errorType":"exception","errorClass":"ThirdPartyException","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/xinghuo/xinghuo.py","lineNumber":173,"sourceCode":"\n    Returns:\n        List of document chunk content\n\n    Raises:\n        ThirdPartyException: Raised when document splitting fails\n        CustomException: Raised when unable to get chunk content\n    \"\"\"\n    if not file_id:\n        raise CustomException(CodeEnum.ParameterCheckException, \"File ID is required\")\n\n    max_retries = 70\n    retry_count = 0\n    data: Optional[List[Dict[str, Any]]] = None\n\n    while retry_count < max_retries:\n        file_status = await get_file_status(file_id=file_id, **kwargs)\n        if file_status and file_status[0][\"fileStatus\"] == \"failed\":\n            raise ThirdPartyException(\"Document splitting failed\")\n\n        if file_status and file_status[0][\"fileStatus\"] in [\"spliting\", \"ocring\"]:\n            logger.info(\n                f\"File: {file_id} - Retry {retry_count + 1}, document is being chunked, continuing to retry...\"\n            )\n            retry_count += 1\n            if retry_count < max_retries:\n                await asyncio.sleep(4)\n                continue\n\n        chunks_url = (\n            os.getenv(\"XINGHUO_RAG_URL\", \"\")\n            + \"openapi/v1/file/chunks?fileId=\"\n            + file_id\n            + \"&multiLable=true\"\n        )\n        response = await async_request({}, chunks_url, \"GET\", **kwargs)\n","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/xinghuo/xinghuo.py#L155-L191","documentation":"While polling in get_chunks(), if the Xinghuo file-status API reports fileStatus == \"failed\" for the given file_id, the client immediately raises this ThirdPartyException. It means the remote splitting/OCR job for the document finished in a failed state on the Xinghuo side.","triggerScenarios":"Calling get_chunks() for a file whose remote split job failed: unsupported or corrupted document, OCR failure on scanned/image PDFs, file rejected by the Xinghuo splitter, or the file was deleted/expired server-side so status resolves to failed.","commonSituations":"Ingesting password-protected or image-only PDFs where OCR fails; uploading files exceeding platform size/format limits; checking chunks of an old file id whose processing previously failed; regional service issues that mark jobs failed.","solutions":["Inspect the file status details from get_file_status() to learn why Xinghuo marked it failed.","Convert the document to a supported format (e.g. text-based PDF, DOCX) and re-upload/re-split.","Re-run the split step for that file; if it fails repeatedly, test with a small known-good document to isolate the file as the cause.","Check Xinghuo service status/quota if even valid files fail."],"exampleFix":"# before\nchunks = await get_chunks(file_id=file_id)\n# after\nstatus = await get_file_status(file_id=file_id)\nif status and status[0][\"fileStatus\"] == \"failed\":\n    logger.warning(\"file %s failed to split, re-uploading\", file_id)\n    file_id = await reupload_and_split(document)\nchunks = await get_chunks(file_id=file_id)","handlingStrategy":"try-catch","validationCode":"status = await get_file_status(file_id=file_id)\nif status and status[0][\"fileStatus\"] == \"failed\":\n    raise RuntimeError(f\"file {file_id} already failed remotely; re-upload before fetching chunks\")","typeGuard":"def split_failed(status_list: list | None) -> bool:\n    return bool(status_list) and status_list[0].get(\"fileStatus\") == \"failed\"","tryCatchPattern":"try:\n    chunks = await get_chunks(file_id=file_id)\nexcept ThirdPartyException as e:\n    if str(e) == \"Document splitting failed\":\n        file_id = await reupload_and_split(document)  # recover path\n        chunks = await get_chunks(file_id=file_id)\n    else:\n        raise","preventionTips":["Check file status once before long polling so you fail immediately on 'failed'.","Use supported, text-extractable document formats; OCR image PDFs yourself if needed.","Log get_file_status() details to diagnose remote failures quickly."],"tags":["third-party","rag","document-splitting","ocr","polling"],"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"}