iflytek/astron-agent · error · ValueError

lengthRange must contain one or two integers

Error message

lengthRange must contain one or two integers

What it means

build_parser_config validates the optional lengthRange parameter used to derive chunk_token_num, and raises ValueError when lengthRange is not a list of one or two true integers (bools are explicitly rejected because bool is a subclass of int in Python). It guards the RAGFlow parser config from malformed chunk-length settings.

Solutions

  1. Validate lengthRange on the API boundary: enforce list of 1-2 ints before calling build_parser_config
  2. Coerce client values with int(value) and reject bools and non-numeric strings
  3. Return a 400 to the caller listing the offending lengthRange value
  4. Fall back to the default chunk_token_num (256) when lengthRange is absent or invalid

Example fix

// before
config = build_parser_config(cfg={"lengthRange": payload.get("lengthRange")})
// after
lr = payload.get("lengthRange") or []
if lr and (len(lr) not in (1, 2) or any(isinstance(v, bool) or not isinstance(v, int) for v in lr)):
    raise HTTPException(400, "lengthRange must contain one or two integers")
config = build_parser_config(cfg={"lengthRange": lr})
Defensive patterns

Strategy: validation

Validate before calling

def validate_length_range(lr) -> list[int] | None:
    if lr in (None, []):
        return None
    if not isinstance(lr, list) or len(lr) not in (1, 2):
        raise ValueError("lengthRange must contain one or two integers")
    if any(isinstance(v, bool) or not isinstance(v, int) for v in lr):
        raise ValueError("lengthRange must contain integers")
    return lr

Type guard

def is_valid_length_range(v) -> bool:
    return (isinstance(v, list) and len(v) in (1, 2)
            and all(isinstance(x, int) and not isinstance(x, bool) for x in v))

Try / catch

try:
    config = build_parser_config(cfg=cfg)
except ValueError as e:
    if "lengthRange" in str(e):
        cfg.pop("lengthRange", None)  # fall back to default 256
        config = build_parser_config(cfg=cfg)
    else:
        raise

Prevention

When it happens

Trigger: Calling build_parser_config with lengthRange=[] (empty), lengthRange=[1,2,3] (three values), or non-int entries like "256", 256.0, True, or None inside the list.

Common situations: JSON payloads from the Astron UI where numbers arrive as strings or floats; empty arrays sent when the user cleared a form field; booleans sneaking in via truthy config toggles; unvalidated passthrough of client config.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at core/knowledge/infra/ragflow/ragflow_utils.py:518

            separator: Separator list
            titleSplit: Whether to split by title

        Returns:
            Parser configuration dictionary
        """
        # RAGFlow's parser uses the configured maximum as its target chunk
        # size. ``overlap`` and ``titleSplit`` are intentionally not forwarded:
        # v0.20.5 has no overlap field, and title splitting is not equivalent
        # to changing PDF layout recognition/OCR mode.
        _ = overlap, titleSplit
        if lengthRange is None:
            chunk_token_num = 256
        else:
            if len(lengthRange) not in (1, 2) or any(
                isinstance(value, bool) or not isinstance(value, int)
                for value in lengthRange
            ):
                raise ValueError("lengthRange must contain one or two integers")
            if any(value <= 0 for value in lengthRange):
                raise ValueError("lengthRange values must be greater than zero")
            if len(lengthRange) == 2 and lengthRange[0] > lengthRange[1]:
                raise ValueError("lengthRange minimum cannot exceed maximum")
            chunk_token_num = lengthRange[-1]

        # The Astron UI can send either a literal ``\\n`` or an actual newline.
        # In RAGFlow v0.20.5, unquoted delimiter characters are independent;
        # a multi-character delimiter must be wrapped in backticks.
        normalized_separators = []
        for value in separator or []:
            normalized = value.replace("\\n", "\n")
            if not normalized:
                continue
            normalized_separators.append(
                normalized if len(normalized) == 1 else f"`{normalized}`"
            )
        if not any("\n" in value for value in normalized_separators):

View on GitHub (pinned to 5e758547a8)