{"record":{"id":"f4991ea09b90c472","repo":"infiniflow/ragflow","slug":"operation-requires-n-to-be-within-the-valid-rang","errorCode":null,"errorMessage":"{operation} requires n to be within the valid range in strict mode, got {n}.","messagePattern":"(.+?) requires n to be within the valid range in strict mode, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"agent/component/list_operations.py","lineNumber":90,"sourceCode":"    def _coerce_n(self):\n        try:\n            return int(getattr(self._param, \"n\", 0))\n        except Exception:\n            return 0\n\n    def _is_strict(self):\n        strict = getattr(self._param, \"strict\", False)\n        if isinstance(strict, str):\n            return strict.strip().lower() in {\"1\", \"true\", \"yes\", \"on\"}\n        return bool(strict)\n\n    def _set_outputs(self, outputs):\n        self._param.outputs[\"result\"][\"value\"] = outputs\n        self._param.outputs[\"first\"][\"value\"] = outputs[0] if outputs else None\n        self._param.outputs[\"last\"][\"value\"] = outputs[-1] if outputs else None\n\n    def _raise_strict_range_error(self, operation, n):\n        raise ValueError(f\"{operation} requires n to be within the valid range in strict mode, got {n}.\")\n\n    def _nth(self):\n        n = self._coerce_n()\n        strict = self._is_strict()\n        if n == 0:\n            if strict:\n                self._raise_strict_range_error(\"nth\", n)\n            outputs = []\n        elif n > 0:\n            if n <= len(self.inputs):\n                outputs = [self.inputs[n - 1]]\n            elif strict:\n                self._raise_strict_range_error(\"nth\", n)\n            else:\n                outputs = []\n        else:\n            if abs(n) <= len(self.inputs):\n                outputs = [self.inputs[n]]","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/component/list_operations.py#L72-L108","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","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."],"exampleFix":"# before\noperations: nth, n: 10, strict: true   # list has 3 items -> ValueError\n\n# after\noperations: nth, n: 3, strict: true    # within range\n# or: strict: false to tolerate out-of-range","handlingStrategy":"validation","validationCode":"n = int(n)\nif strict and (n <= 0 or n > len(inputs)):\n    n = max(1, min(n, len(inputs)))  # or raise with a clear message before the component does","typeGuard":null,"tryCatchPattern":"try:\n    comp._invoke()\nexcept ValueError as e:\n    if 'valid range in strict mode' in str(e):\n        # clamp n or disable strict, then retry\n        ...","preventionTips":["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."],"tags":["list-operations","range-validation","strict-mode"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}