gohugoio/hugo · error

nil is not a valid key to group by

Error message

nil is not a valid key to group by

What it means

`group` requires a non-nil key (the group label) as its first argument; Hugo checks this before delegating to the Pages `Grouper` implementation. A nil key would produce a group with no usable name, so it's rejected up front.

Source

Thrown at tpl/collections/collections.go:314

					}

					ins.handleValuePair(l1vv, l2vv)
				}
			}
			return ins.r.Interface(), nil
		default:
			return nil, errors.New("can't iterate over " + reflect.ValueOf(l2).Type().String())
		}
	default:
		return nil, errors.New("can't iterate over " + reflect.ValueOf(l1).Type().String())
	}
}

// Group groups a set of items by the given key.
// This is currently only supported for Pages.
func (ns *Namespace) Group(key any, items any) (any, error) {
	if key == nil {
		return nil, errors.New("nil is not a valid key to group by")
	}

	if g, ok := items.(collections.Grouper); ok {
		return g.Group(key, items)
	}

	in := newSliceElement(items)

	if g, ok := in.(collections.Grouper); ok {
		return g.Group(key, items)
	}

	return nil, fmt.Errorf("grouping not supported for type %T %T", items, in)
}

// IsSet returns whether a given array, channel, slice, or map in c has the given key
// defined.
func (ns *Namespace) IsSet(c any, key any) (bool, error) {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Default the key to a string: `{{ $g := group (.Params.category | default "uncategorized") $pages }}`.
2. Verify argument order — key first, pages second: `{{ group "recent" $pages }}`.
3. Filter out or pre-bucket items whose grouping field is missing before calling group.

Example fix

<!-- before -->
{{ $g := group .Params.series .Pages }}
<!-- after -->
{{ $g := group (.Params.series | default "other") .Pages }}

{{ $key := .Params.groupKey | default "Section" }}
{{ if $key }}{{ $groups := .Pages.GroupByParam $key }}{{ end }}

When it happens

Trigger: `{{ group nil $pages }}` or `{{ group .Params.section $pages }}` where the param is unset, e.g. building grouped lists with a key read from front matter or a loop variable that can be nil.

Common situations: Grouping pages by a front-matter field that some pages omit, passing an unset scratch/variable as the key, or reversing the argument order so the pages land in the key slot as nil after a bad lookup.

Related errors

• sequence must be provided
• can't iterate over a nil value
• both limit and seq must be provided
• grouping not supported for type %T %T
• symdiff: failed to convert value: %w

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