gohugoio/hugo · error

sequence must be provided

Error message

sequence must be provided

What it means

Hugo's `sort` (collections.Sort) requires a collection as its first argument. In tpl/collections/sort.go the function immediately checks `l == nil` and returns this error, failing fast rather than sorting nothing. It means the value handed to `sort` was a literal untyped nil at the template level.

Source

Thrown at tpl/collections/sort.go:33

import (
	"context"
	"errors"
	"reflect"
	"sort"
	"strings"

	"github.com/gohugoio/hugo/common/hmaps"
	"github.com/gohugoio/hugo/common/hreflect"
	"github.com/gohugoio/hugo/langs"
	"github.com/gohugoio/hugo/tpl/compare"
	"github.com/spf13/cast"
)

// Sort returns a sorted copy of the list l.
func (ns *Namespace) Sort(ctx context.Context, l any, args ...any) (any, error) {
	if l == nil {
		return nil, errors.New("sequence must be provided")
	}

	seqv, isNil := hreflect.Indirect(reflect.ValueOf(l))
	if isNil {
		return nil, errors.New("can't iterate over a nil value")
	}

	ctxv := reflect.ValueOf(ctx)

	var sliceType reflect.Type
	switch seqv.Kind() {
	case reflect.Array, reflect.Slice:
		sliceType = seqv.Type()
	case reflect.Map:
		sliceType = reflect.SliceOf(seqv.Type().Elem())
	default:
		return nil, errors.New("can't sort " + reflect.ValueOf(l).Type().String())
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Guard the call: `{{ with .Params.tags }}{{ sort . }}{{ end }}`.
2. Provide a default: `{{ sort (.Params.tags | default slice) }}`.
3. Verify the front-matter/config key actually exists and is spelled correctly on all pages that render the template.

Example fix

<!-- before -->
{{ range sort .Params.tags }}...{{ end }}
<!-- after -->
{{ range sort (.Params.tags | default slice) }}...{{ end }}

{{ $seq := .Params.items }}
{{ if $seq }}{{ sort $seq }}{{ end }}

{{ with try (sort $seq "weight") }}{{ if .Err }}{{ warnf "sort failed: %s" .Err }}{{ else }}{{ range .Value }}...{{ end }}{{ end }}{{ end }}

When it happens

Trigger: `{{ sort .Params.missing }}` where the key doesn't exist, `{{ sort nil }}`, or `{{ sort (.Store.Get "key") }}` when the store entry was never set — any expression that evaluates to untyped nil passed as the sequence.

Common situations: Sorting a front-matter or site param that isn't defined on every page (e.g. `sort .Params.tags` on pages without tags); sorting the result of `where`/`index` lookups against missing keys; config keys renamed between Hugo versions leaving templates referencing nil params.

Related errors

• can't iterate over a nil value
• both limit and seq must be provided
• nil is not a valid key to group by
• symdiff: failed to convert value: %w
• arguments to symdiff must be slices or arrays

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/14f8ead909124ec7.json. Report an issue: GitHub ↗.