iflytek/astron-agent · error · ValueError

Either fileUrl or file must be provided

Error message

Either fileUrl or file must be provided

What it means

Raised by _validate_split_parameters (core/knowledge/service/impl/ragflow_strategy.py:193) when split() is invoked with neither fileUrl nor a file object in kwargs. The RAGFlow split strategy requires exactly one file input source — either a URL/path or an uploaded file — to upload and parse into chunks.

Solutions

1. Pass exactly one input: either fileUrl='https://...' (URL or accessible path) or file=<uploaded file object> via kwargs.
2. If using the HTTP API, ensure the request is multipart/form-data with a populated 'file' part.
3. Check the calling code that assembles split() kwargs — the input key may be named differently (e.g. 'file_url') and silently dropped by **kwargs.
4. Validate inputs client-side before invoking split so the user gets an actionable message.

Example fix

// before
chunks = await strategy.split()  # neither source provided

// after
chunks = await strategy.split(fileUrl="https://example.com/doc.pdf")
// or
chunks = await strategy.split(**{"file": uploaded_file})

def ensure_split_input(fileUrl, file):
    if not fileUrl and not file:
        raise ValueError("split requires fileUrl or file")
    if fileUrl and file:
        raise ValueError("provide only one of fileUrl and file")

def has_file_input(fileUrl, file) -> bool:
    return bool(file) or isinstance(fileUrl, str) and bool(fileUrl.strip())

try:
    chunks = await strategy.split(**split_kwargs)
except ValueError as e:
    return {"error": "invalid_input", "detail": str(e), "hint": "attach a file or set fileUrl"}

When it happens

Trigger: Calling strategy.split() with no arguments, or with fileUrl=None and no 'file' key in kwargs; also when the caller passes an empty string for fileUrl (falsy) and no file.

Common situations: Frontend form submitted without attaching a file or filling the fileUrl field; API layer dropped the multipart file during request forwarding; caller intended re-slicing with only document_id but forgot the new file source; a code path constructs split kwargs dynamically and misses the input key.

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

• Cannot provide both fileUrl and file parameters
• PARAMS_ERROR
• BOT_NOT_EXISTS
• RESPONSE_FAILED
• 9020

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

Appendix: source

Thrown at core/knowledge/service/impl/ragflow_strategy.py:193

        results = RagflowUtils.convert_ragflow_query_response(
            ragflow_response, threshold
        )
        if effective_top_k and effective_top_k > 0:
            results = results[:effective_top_k]

        logger.info("Query completed, returning %d results", len(results))
        return {"query": query, "count": len(results), "results": results}

    def _empty_query_result(self, query: str) -> Dict[str, Any]:
        """Unified empty-result format for query paths."""
        return {"query": query, "count": 0, "results": []}

    def _validate_split_parameters(
        self, fileUrl: Optional[str], file: Optional[Any]
    ) -> None:
        """Validate split method parameters."""
        if not fileUrl and not file:
            raise ValueError("Either fileUrl or file must be provided")
        if fileUrl and file:
            raise ValueError("Cannot provide both fileUrl and file parameters")

    def _parse_form_data_parameters(
        self,
        lengthRange: Optional[List[int]],
        separator: Optional[List[str]],
        cutOff: Optional[List[str]],
    ) -> tuple[Optional[List[int]], Optional[List[str]], Optional[List[str]]]:
        """Parse form-data parameters from JSON strings."""
        parsed_length_range = lengthRange
        parsed_separator = separator
        parsed_cut_off = cutOff

        if isinstance(lengthRange, str):
            try:
                parsed_length_range = json.loads(lengthRange) if lengthRange else None
            except (json.JSONDecodeError, TypeError):

View on GitHub (pinned to 5e758547a8)