iflytek/astron-agent · error · ProtocolParamException

file is required

Error message

file is required

What it means

CbgStrategy.split raises ProtocolParamException('file is required') when neither fileUrl nor kwargs['file'] is provided. Unlike AIUI, the CBG strategy can split from an uploaded file, but it requires at least one of the two inputs.

Solutions

1. Pass either fileUrl or the uploaded file (kwargs['file']) to split()
2. Check the caller uses the exact kwarg name 'file' for the upload
3. Verify the document upload pipeline produced a file/URL before invoking split
4. If you have a URL only, set fileUrl; if you have bytes/UploadFile, pass file=

Example fix

// before
await strategy.split(separator=["。"])  # no file/fileUrl
// after
await strategy.split(file=upload_file, separator=["。"])
// or
await strategy.split(fileUrl="https://oss.example.com/doc.pdf", separator=["。"])

file = kwargs.get("file")
if not fileUrl and not file:
    raise ValueError("Provide either fileUrl or an uploaded 'file' before calling split")

def has_split_input(fileUrl, kwargs: dict) -> bool:
    return bool(fileUrl) or bool(kwargs.get("file"))

try:
    chunks = await strategy.split(file=file)
except ProtocolParamException as e:
    logger.warning(f"Missing parameter: {e.msg}")
    raise BadRequest(e.msg)

When it happens

Trigger: Calling split() with fileUrl=None and no 'file' entry in kwargs — the caller supplied neither a URL nor an uploaded file object/bytes.

Common situations: Upload step failed or was skipped so no file reached the strategy; wrong kwarg name used (e.g. 'file_url' or 'filePath' instead of file/fileUrl); request payload missing the multipart file part.

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

• LONG_CONTENT_CHAT_ID_ERROR
• PARAMETER_ERROR
• LONG_CONTENT_WRONG_BUSINESS_TYPE
• LONG_CONTENT_MISS_FILE_INFO
• LONG_CONTENT_FILE_SIZE_OUT_LIMIT

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

Appendix: source

Thrown at core/knowledge/service/impl/cbg_strategy.py:199

        Split file into multiple chunks

        Args:
            fileUrl: File URL
            lengthRange: Length range
            overlap: Overlap length
            resourceType: Resource type
            separator: Separator list
            titleSplit: Whether to split by title
            cutOff: Cutoff marker list
            **kwargs: Other parameters

        Returns:
            List of split chunks
        """
        if fileUrl is None:
            fileUrl = ""
            if not kwargs.get("file"):
                raise ProtocolParamException(msg="file is required")

        data = []
        wiki_split_extends: Dict[str, Any] = {}

        if check_not_empty(separator) and separator is not None:
            split_chars = []
            for chars in separator:
                split_chars.append(
                    base64.b64encode(chars.encode("utf-8")).decode(encoding="utf-8")
                )
            wiki_split_extends["chunkSeparators"] = split_chars
        else:
            wiki_split_extends["chunkSeparators"] = ["DQo="]

        if (
            check_not_empty(lengthRange)
            and lengthRange is not None
            and len(lengthRange) > 1

View on GitHub (pinned to 5e758547a8)