gohugoio/hugo · error

sequence must be provided

Error message

sequence must be provided

What it means

The `sort` template function returns a sorted copy of a list. If the list argument is the literal Go `nil` interface value (not a typed nil), this error fires. The check at sort.go:32 distinguishes a truly absent/nil sequence from a typed nil pointer, which produces a different error.

Solutions

1. Default the value to an empty slice before sorting: `{{ $list = $list | default slice }}` then `{{ sort $list }}`.
2. Fix the upstream data source so the variable is always a slice or map.
3. Add a conditional: `{{ with $list }}{{ sort . }}{{ end }}`.

Example fix

// before
{{ sort .MaybeNilList }}
// after
{{ $list := .MaybeNilList | default slice }}
{{ sort $list }}

{{ with $list }}{{ sort . }}{{ else }}{{ slice }}{{ end }}

func isNonNilSequence(v any) bool {
    if v == nil { return false }
    kind := reflect.TypeOf(v).Kind()
    return kind == reflect.Slice || kind == reflect.Array || kind == reflect.Map
}

When it happens

Trigger: Calling `{{ sort nil }}` or passing a template variable that is unset and evaluates to the untyped nil interface, e.g. `{{ sort .NonexistentVariable }}` where the variable was never assigned.

Common situations: A template references a `.Scratch.Get` result that was never set, or a partial receives an empty context, yielding untyped nil. The developer expected an empty slice but got nil.

Related errors

• both count and seq must be provided
• can't iterate over a nil value
• can't sort
• cannot index slice/array with nil
• nil is not a valid key to group by

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/14f8ead909124ec7. Report an issue: GitHub.

Appendix: 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 52c9bd7908)