iflytek/astron-agent · error · ThirdPartyException

Document splitting failed

Error message

Document splitting failed

What it means

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.

Solutions

1. Inspect the file status details from get_file_status() to learn why Xinghuo marked it failed.
2. Convert the document to a supported format (e.g. text-based PDF, DOCX) and re-upload/re-split.
3. 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.
4. Check Xinghuo service status/quota if even valid files fail.

Example fix

# before
chunks = await get_chunks(file_id=file_id)
# after
status = await get_file_status(file_id=file_id)
if status and status[0]["fileStatus"] == "failed":
    logger.warning("file %s failed to split, re-uploading", file_id)
    file_id = await reupload_and_split(document)
chunks = await get_chunks(file_id=file_id)

status = await get_file_status(file_id=file_id)
if status and status[0]["fileStatus"] == "failed":
    raise RuntimeError(f"file {file_id} already failed remotely; re-upload before fetching chunks")

def split_failed(status_list: list | None) -> bool:
    return bool(status_list) and status_list[0].get("fileStatus") == "failed"

try:
    chunks = await get_chunks(file_id=file_id)
except ThirdPartyException as e:
    if str(e) == "Document splitting failed":
        file_id = await reupload_and_split(document)  # recover path
        chunks = await get_chunks(file_id=file_id)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Document splitting failed after retries
• GetFileContentFailed
• {desc from XINGHUO-RAG response}
• Failed to 【XINGHUO-RAG】; code
• RAGFLOW_RAGError

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

Appendix: source

Thrown at core/knowledge/infra/xinghuo/xinghuo.py:173

    Returns:
        List of document chunk content

    Raises:
        ThirdPartyException: Raised when document splitting fails
        CustomException: Raised when unable to get chunk content
    """
    if not file_id:
        raise CustomException(CodeEnum.ParameterCheckException, "File ID is required")

    max_retries = 70
    retry_count = 0
    data: Optional[List[Dict[str, Any]]] = None

    while retry_count < max_retries:
        file_status = await get_file_status(file_id=file_id, **kwargs)
        if file_status and file_status[0]["fileStatus"] == "failed":
            raise ThirdPartyException("Document splitting failed")

        if file_status and file_status[0]["fileStatus"] in ["spliting", "ocring"]:
            logger.info(
                f"File: {file_id} - Retry {retry_count + 1}, document is being chunked, continuing to retry..."
            )
            retry_count += 1
            if retry_count < max_retries:
                await asyncio.sleep(4)
                continue

        chunks_url = (
            os.getenv("XINGHUO_RAG_URL", "")
            + "openapi/v1/file/chunks?fileId="
            + file_id
            + "&multiLable=true"
        )
        response = await async_request({}, chunks_url, "GET", **kwargs)

View on GitHub (pinned to 5e758547a8)