iflytek/astron-agent · error · ThirdPartyException

File ID is required for split operation

Error message

File ID is required for split operation

What it means

The split() function in the Xinghuo (讯飞星火) ingestion client calls the chunking/split HTTP API, which requires a fileId to identify the document to split. It raises ThirdPartyException when file_id is falsy (None or empty string), failing fast before a doomed API call is made.

Solutions

  1. Check the file_id returned by the upload step and fail the pipeline there if it is missing
  2. Verify the key used to extract the file id from the upload response matches the actual Xinghuo API response
  3. Make split calls conditional on a truthy file_id and surface a clear upstream error
  4. Add logging of the upload response before split to trace where the id is lost

Example fix

// before
result = await split(upload_result)  # upload_result['fileId'] may be missing
// after
file_id = upload_result.get("fileId")
if not file_id:
    raise PipelineError(f"upload returned no file id: {upload_result}")
result = await split(file_id)
Defensive patterns

Strategy: validation

Validate before calling

if not file_id or not isinstance(file_id, str):
    raise ValueError(f"cannot split: invalid file_id {file_id!r}")

Type guard

def has_file_id(v) -> bool:
    return isinstance(v, str) and len(v.strip()) > 0

Try / catch

try:
    result = await split(file_id)
except ThirdPartyException as e:
    if "File ID is required" in str(e):
        logger.error("split skipped: no file id; upload result was %s", upload_result)
        raise PipelineError("upload step did not produce a file id") from e
    raise

Prevention

When it happens

Trigger: Calling split(file_id=None) or split("") — typically because the preceding upload step failed to return a file id, the upload response was parsed with the wrong key, or the id was lost between pipeline steps.

Common situations: Upload API response schema changed so the file id key no longer matches; upload silently failed but the pipeline continued; None propagated from a lookup miss in an ingestion DAG; env-specific Xinghuo upload misconfiguration.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

    length_range: Optional[List[int]] = None,
    **kwargs: Any,
) -> Dict[str, Any]:
    """
    Perform chunking processing on documents.

    Args:
        file_id: File ID
        cut_off: Cutoff character list
        length_range: Chunk length range

    Returns:
        Result data of chunking operation

    Raises:
        ThirdPartyException: Raised when chunking fails
    """
    if not file_id:
        raise ThirdPartyException("File ID is required for split operation")

    post_body = {
        "fileIds": [file_id],
        "isSplitDefault": False,
        "splitType": "wiki",
        "wikiSplitExtends": {},
    }

    split_chars = []
    if cut_off:
        for s in cut_off:
            split_chars.append(
                base64.b64encode(s.encode("utf-8")).decode(encoding="utf-8")
            )

    post_body["wikiSplitExtends"] = {
        "chunkSeparators": split_chars,
        "minChunkSize": (

View on GitHub (pinned to 5e758547a8)