gohugoio/hugo · error

index of untyped nil

Error message

index of untyped nil

What it means

Returned by the index builtin when the very first item to be indexed is reflect-invalid (untyped nil), before any indexing happens. This means you tried to index something that has no concrete type at all, e.g. {{index nil 0}} or indexing an unset/absent variable.

Source

Thrown at tpl/internal/go_templates/texttemplate/funcs.go:201

		return 0, fmt.Errorf("cannot index slice/array with nil")
	default:
		return 0, fmt.Errorf("cannot index slice/array with type %s", index.Type())
	}
	if x < 0 || int(x) < 0 || int(x) > cap {
		return 0, fmt.Errorf("index out of range: %d", x)
	}
	return int(x), nil
}

// Indexing.

// index returns the result of indexing its first argument by the following
// arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
// indexed item must be a map, slice, or array.
func index(item reflect.Value, indexes ...reflect.Value) (reflect.Value, error) {
	item = indirectInterface(item)
	if !item.IsValid() {
		return reflect.Value{}, fmt.Errorf("index of untyped nil")
	}
	for _, index := range indexes {
		index = indirectInterface(index)
		var isNil bool
		if item, isNil = indirect(item); isNil {
			return reflect.Value{}, fmt.Errorf("index of nil pointer")
		}
		switch item.Kind() {
		case reflect.Array, reflect.Slice, reflect.String:
			x, err := indexArg(index, item.Len())
			if err != nil {
				return reflect.Value{}, err
			}
			item = item.Index(x)
		case reflect.Map:
			index, err := prepareArg(index, item.Type().Key())
			if err != nil {
				return reflect.Value{}, err

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Guard the index call: {{if .Items}}{{index .Items 0}}{{end}}.
2. Ensure the collection is non-nil before render (initialize empty slices/maps in the data).
3. Use with for nil-safe scoping: {{with .Items}}{{index . 0}}{{end}}.
4. Provide defaults in the data layer so the value is never an untyped nil.

Example fix

// before
{{index .List 0}} // .List is nil interface -> error

// after
{{with .List}}{{index . 0}}{{end}}
// or ensure .List is []any{} in data

// ensure collections are non-nil in the data layer
type PageData struct{ Items []any }
func sanitize(d *PageData) {
    if d.Items == nil { d.Items = []any{} }
}

func isIndexable(v any) bool {
    if v == nil { return false }
    switch reflect.TypeOf(v).Kind() {
    case reflect.Slice, reflect.Array, reflect.Map, reflect.String:
        return true
    }
    return false
}

When it happens

Trigger: Calling {{index .MaybeNil 0}} where .MaybeNil is a nil interface (no concrete value); indexing a variable that was never assigned; indexing the result of a pipeline that produced nothing.

Common situations: Optional context field that is nil and used directly with index; a partial invoked with nil data then indexed; conditional data not populated in some branches.

Related errors

• cannot index slice/array with nil
• cannot index slice/array with type %s
• index of nil pointer
• value is nil; should be of type %s
• invalid function signature for %s: second return value shoul

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