iflytek/astron-agent · error · ThirdPartyException

Document splitting failed after retries

Error message

Document splitting failed after retries

What it means

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.

Solutions

1. Verify XINGHUO_RAG_URL is set and reachable (curl the host) and that Xinghuo auth headers/credentials are valid.
2. 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).
3. Check network egress/DNS from the deployment environment; the 3 retries with 1s sleep expire in ~2s, so transient outages easily exhaust them.
4. If transient upstream flakiness is common, increase max_retries or backoff in split(), or re-run the ingestion job later.

Example fix

# before
response = await async_request(post_body, os.getenv("XINGHUO_RAG_URL", "") + "openapi/v1/file/split", **kwargs)
# after
base = os.getenv("XINGHUO_RAG_URL")
if not base:
    raise ValueError("XINGHUO_RAG_URL is not configured")
response = await async_request(post_body, base + "openapi/v1/file/split", **kwargs)

base = os.getenv("XINGHUO_RAG_URL")
if not base:
    raise RuntimeError("XINGHUO_RAG_URL must be set before splitting documents")
# optionally pre-check reachability:
# await aiohttp.ClientSession().head(base)

def has_file_id(result: dict | None) -> bool:
    return isinstance(result, dict) and bool(result.get("fileId"))

try:
    data = await split(document)
except ThirdPartyException as e:
    logger.error("Xinghuo split failed: %s", e)
    raise DocumentIngestionError(str(e)) from e

When it happens

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

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

Related errors

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

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

Appendix: source

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

    while retry_count < max_retries:
        try:
            response = await async_request(
                post_body,
                os.getenv("XINGHUO_RAG_URL", "") + "openapi/v1/file/split",
                **kwargs,
            )
            data = response
            break
        except Exception:
            print(
                f"Retry {retry_count + 1}, document splitting not successful, continuing to retry..."
            )
            retry_count += 1
            if retry_count < max_retries:
                await asyncio.sleep(1)

    if data is None:
        raise ThirdPartyException("Document splitting failed after retries")

    return data


async def get_chunks(
    file_id: Optional[str] = None, **kwargs: Any
) -> List[Dict[str, Any]]:
    """
    Get document chunk content.

    Args:
        file_id: File ID

    Returns:
        List of document chunk content

    Raises:
        ThirdPartyException: Raised when document splitting fails

View on GitHub (pinned to 5e758547a8)