infiniflow/ragflow · error · ValueError

{operation} requires n to be within the valid range in stric

Error message

{operation} requires n to be within the valid range in strict mode, got {n}.

What it means

ValueError raised by ListOperations helper _raise_strict_range_error when strict mode is enabled and the requested n for an operation (nth/head/tail) falls outside the valid range for the current input. In strict mode the component refuses to silently return empty results for out-of-range indices.

Source

Thrown at agent/component/list_operations.py:90

    def _coerce_n(self):
        try:
            return int(getattr(self._param, "n", 0))
        except Exception:
            return 0

    def _is_strict(self):
        strict = getattr(self._param, "strict", False)
        if isinstance(strict, str):
            return strict.strip().lower() in {"1", "true", "yes", "on"}
        return bool(strict)

    def _set_outputs(self, outputs):
        self._param.outputs["result"]["value"] = outputs
        self._param.outputs["first"]["value"] = outputs[0] if outputs else None
        self._param.outputs["last"]["value"] = outputs[-1] if outputs else None

    def _raise_strict_range_error(self, operation, n):
        raise ValueError(f"{operation} requires n to be within the valid range in strict mode, got {n}.")

    def _nth(self):
        n = self._coerce_n()
        strict = self._is_strict()
        if n == 0:
            if strict:
                self._raise_strict_range_error("nth", n)
            outputs = []
        elif n > 0:
            if n <= len(self.inputs):
                outputs = [self.inputs[n - 1]]
            elif strict:
                self._raise_strict_range_error("nth", n)
            else:
                outputs = []
        else:
            if abs(n) <= len(self.inputs):
                outputs = [self.inputs[n]]

View on GitHub (pinned to 554fb1133a)

Solutions

Clamp n to the list length before the operation, or choose an n guaranteed within range for your data.
Disable strict mode (set strict=false) if you prefer empty output instead of an error for out-of-range n.
For 'take first if present' semantics, use head with n=1 rather than nth with a large fixed index.

Example fix

# before
operations: nth, n: 10, strict: true   # list has 3 items -> ValueError

# after
operations: nth, n: 3, strict: true    # within range
# or: strict: false to tolerate out-of-range

Defensive patterns

Strategy: validation

Validate before calling

n = int(n)
if strict and (n <= 0 or n > len(inputs)):
    n = max(1, min(n, len(inputs)))  # or raise with a clear message before the component does

Try / catch

try:
    comp._invoke()
except ValueError as e:
    if 'valid range in strict mode' in str(e):
        # clamp n or disable strict, then retry
        ...

Prevention

Clamp n to 1..len(list) when data length varies.
Turn off strict mode when empty results are acceptable for out-of-range n.
Use head with small n instead of large fixed nth indices.

When it happens

Trigger: operations='nth' with n=0 (invalid 1-based index) or n greater than len(inputs) while strict=true; head/tail with n exceeding list length or negative in strict mode. The 'strict' parameter accepts booleans or the strings '1'/'true'/'yes'/'on'.

Common situations: Hard-coded n (e.g. extract the 5th item) against variable-length lists that sometimes have fewer elements; leaving strict enabled from a template while feeding short test inputs; passing n=0 expecting a null result.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/f4991ea09b90c472. Report an issue: GitHub.