{"record":{"id":"717e626ff118211d","repo":"infiniflow/ragflow","slug":"listoperations-head-requires-n-to-be-within-the-v","errorCode":null,"errorMessage":"ListOperations: head requires n to be within the valid range in strict mode, got %d","messagePattern":"ListOperations: head requires n to be within the valid range in strict mode, got (.+?)","errorType":"validation","errorClass":"listOpPanic","httpStatus":null,"severity":"error","filePath":"internal/agent/component/list_operations.go","lineNumber":414,"sourceCode":"\t\t}\n\t\treturn []any{}\n\t}\n\tabsN := -n\n\tif absN <= len(items) {\n\t\treturn []any{items[n]}\n\t}\n\tif l.param.Strict {\n\t\tpanic(strictRangePanic(\"nth\", n))\n\t}\n\treturn []any{}\n}\n\n// opHead: first n items. n < 1 → empty. Strict: 1 ≤ n ≤ len(items).\nfunc (l *ListOperationsComponent) opHead(items []any) []any {\n\tn := l.param.N\n\tif l.param.Strict {\n\t\tif n < 1 || n > len(items) {\n\t\t\tpanic(strictRangePanic(\"head\", n))\n\t\t}\n\t\treturn append([]any{}, items[:n]...)\n\t}\n\tif n < 1 {\n\t\treturn []any{}\n\t}\n\tif n > len(items) {\n\t\tn = len(items)\n\t}\n\treturn append([]any{}, items[:n]...)\n}\n\n// opTail: last n items. n < 1 → empty. Strict: 1 ≤ n ≤ len(items).\nfunc (l *ListOperationsComponent) opTail(items []any) []any {\n\tn := l.param.N\n\tif l.param.Strict {\n\t\tif n < 1 || n > len(items) {\n\t\t\tpanic(strictRangePanic(\"tail\", n))","sourceCodeStart":396,"sourceCodeEnd":432,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/internal/agent/component/list_operations.go#L396-L432","documentation":"opHead panics in strict mode when n < 1 or n > len(items). Strict mode enforces the full contract 1 <= n <= len(items) for the head operation (first n items); zero, negative, or oversized n is treated as a caller error and panics via strictRangePanic instead of being clamped or returning an empty list.","triggerScenarios":"ListOperations with operation head, Strict: true, and N set to 0, negative, or greater than the number of input items.","commonSituations":"N defaults to 0 because the parameter was never set; a computed count evaluates to 0 on empty/filtered upstream lists; hardcoded head size from a larger dataset reused on a smaller one.","solutions":["Set N to a value between 1 and the input list length","If the upstream list can be empty, branch before head runs (strict head on an empty list always violates 1 <= n)","Turn strict mode off to get the lenient behavior: n < 1 returns empty, n > len clamps to the whole list"],"exampleFix":"# before\noperation: head\nstrict: true\nn: 0        # panic: head requires n to be within the valid range\n\n# after\noperation: head\nstrict: true\nn: 1        # first item","handlingStrategy":"validation","validationCode":"if op == \"head\" && strict && (n < 1 || n > len(items)) {\n    return fmt.Errorf(\"head requires 1 <= n <= %d, got %d\", len(items), n)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never leave N unset (zero default) on strict head/tail components","Branch on empty upstream lists before strict head runs","For dynamic sizes, compute n as min(desired, len(items)) and ensure it stays >= 1"],"tags":["go","list-operations","agent-component","strict-mode","panic","range-check"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}