{"id":"99de922e37331615","repo":"gohugoio/hugo","slug":"sequence-length-must-be-non-negative","errorCode":null,"errorMessage":"sequence length must be non-negative","messagePattern":"sequence length must be non-negative","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/collections/collections.go","lineNumber":208,"sourceCode":"\t\tdict[key] = values[i+1]\n\t}\n\n\treturn root, nil\n}\n\n// First returns the first limit items in list l.\nfunc (ns *Namespace) First(limit any, l any) (any, error) {\n\tif limit == nil || l == nil {\n\t\treturn nil, errors.New(\"both limit and seq must be provided\")\n\t}\n\n\tlimitv, err := cast.ToIntE(limit)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif limitv < 0 {\n\t\treturn nil, errors.New(\"sequence length must be non-negative\")\n\t}\n\n\tlv := reflect.ValueOf(l)\n\tlv, isNil := hreflect.Indirect(lv)\n\tif isNil {\n\t\treturn nil, errors.New(\"can't iterate over a nil value\")\n\t}\n\n\tswitch lv.Kind() {\n\tcase reflect.Array, reflect.Slice, reflect.String:\n\t\t// okay\n\tdefault:\n\t\treturn nil, errors.New(\"can't iterate over \" + reflect.ValueOf(l).Type().String())\n\t}\n\n\tif limitv > lv.Len() {\n\t\tlimitv = lv.Len()\n\t}","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/collections/collections.go#L190-L226","documentation":"The `first` function rejects a negative limit after converting it to int: you cannot take the first -1 items of a sequence. (A limit larger than the list is fine — it's clamped to the list length — but negative is treated as a programming error.)","triggerScenarios":"`{{ first -1 .Pages }}` or a computed limit that goes negative, e.g. `{{ first (sub $shown $total) .Pages }}` when `$total > $shown`.","commonSituations":"Arithmetic on pagination or 'remaining items' counts underflowing below zero, config values set to -1 intending 'unlimited' (Hugo's `first` has no such convention), or subtracting an offset from a count without clamping.","solutions":["Clamp the computed limit: `{{ $n := math.Max 0 (sub $total $offset) }}{{ first $n .Pages }}`.","For 'all items', skip `first` entirely and range the collection directly instead of passing -1.","Trace where the negative value originates (config, front matter, arithmetic) and fix it at the source."],"exampleFix":"<!-- before -->\n{{ range first (sub 3 (len .Pages)) .Pages }}...{{ end }}\n<!-- after -->\n{{ range first (math.Max 0 (sub 3 (len .Pages))) .Pages }}...{{ end }}","handlingStrategy":"validation","validationCode":"{{ $n := sub (len .Pages) 3 }}\n{{ if ge $n 0 }}{{ range seq $n }}...{{ end }}{{ end }}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp computed lengths before calling seq: `{{ $n := math.Max 0 $n }}`","Be careful with subtraction producing negatives when a collection is smaller than expected","Guard seq calls driven by user/front-matter values with an explicit `ge $n 0` check"],"tags":["hugo","templates","collections","first","bounds"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}