What causes "The lengthRange must be an array of integers" in iflytek/astron-agent?

Send lengthRange as a JSON array of plain integers, e.g. lengthRange=%5B1%2C100%5D for [1,100].

iflytek/astron-agent · warning · ProtocolParamException

The lengthRange must be an array of integers

Error message

The lengthRange must be an array of integers

What it means

ProtocolParamException raised by parse_length_range in the knowledge service upload API when the lengthRange query/form parameter parses as JSON but contains non-integer elements (e.g. floats or strings). The API requires an array of integers like [1,100].

Solutions

Send lengthRange as a JSON array of plain integers, e.g. lengthRange=%5B1%2C100%5D for [1,100].
On the client, coerce values before sending: JSON.stringify([Math.trunc(min), Math.trunc(max)]).
If decimals are legitimate, ask the backend to relax the check or round server-side.
Validate the payload with JSON.parse and Array.every(Number.isInteger) before calling the API.

Example fix

// before
const lengthRange = [chunkMin.toFixed(0) + '', chunkMax + '']; // ["1","100"] strings
// after
const lengthRange = [Math.trunc(chunkMin), Math.trunc(chunkMax)]; // [1,100]
if (!lengthRange.every(Number.isInteger)) throw new Error('lengthRange must be integers');
body.append('lengthRange', JSON.stringify(lengthRange));

Defensive patterns

Strategy: validation

Validate before calling

import json
def valid_length_range(raw):
    try:
        val = json.loads(raw)
    except (json.JSONDecodeError, ValueError):
        return False
    return isinstance(val, list) and len(val) == 2 and all(isinstance(x, int) and not isinstance(x, bool) for x in val)
# call the API only if valid_length_range(length_range_param)

Type guard

def is_int_array(val) -> bool:
    return isinstance(val, list) and all(isinstance(x, int) and not isinstance(x, bool) for x in val)

Prevention

Serialize numeric params with JSON.stringify/json.dumps, never string concatenation.
Note that Python bool is a subclass of int — reject true/false explicitly if ambiguity matters.
Validate parameters client-side before each upload request.
Document the exact expected format ([min,max] integers) in the API client.

When it happens

Trigger: file_upload receives lengthRange='[1.0, 100]' or '["1", "100"]' — json.loads succeeds but all(isinstance(x, int)) fails, so ProtocolParamException is raised intentionally.

Common situations: Frontend serializes numbers as floats (1.0) or strings; clients send ranges quoted incorrectly; Swagger/curl users passing JSON with decimal bounds; JS JSON.stringify producing floats from computed values.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at core/knowledge/api/v1/api.py:267

            lengthRange=split_request.lengthRange,
            overlap=split_request.overlap,
            separator=split_request.separator,
            titleSplit=split_request.titleSplit,
            cutOff=split_request.cutOff,
            document_id=split_request.documentId,
            group=split_request.group,
            datasetId=split_request.datasetId,
        )


async def parse_length_range(lengthRange: Optional[str]) -> Optional[List[int]]:
    parsed_length_range = None
    if lengthRange:
        try:
            parsed_length_range = json.loads(lengthRange)
            # Invalid
            if not all(isinstance(x, int) for x in parsed_length_range):
                raise ProtocolParamException(
                    msg="The lengthRange must be an array of integers"
                )
        except (json.JSONDecodeError, ValueError) as e:
            raise ProtocolParamException(
                msg=f"Invalid lengthRange format: {str(e)}；The lengthRange must be an array of integers"
            )
    return parsed_length_range


async def parse_separator(separator: Optional[str]) -> Optional[List[str]]:
    parsed_separator = None
    if separator:
        try:
            parsed_separator = json.loads(separator)
            # Invalid
            if not all(isinstance(x, str) for x in parsed_separator):
                raise ProtocolParamException(
                    msg="The separator must be an array of strings"

View on GitHub (pinned to 5e758547a8)