{key} is a Page method but you can't use it with GroupBy

Error message

{key} is a Page method but you can't use it with GroupBy

What it means

`Pages.GroupBy` reflects the named Page method to group by it. It requires the method to return a usable group key: either a single non-error value, or (value, error). The first guard (pagegroup.go:129-130) rejects methods that return zero values or more than two values, since there is no groupable key to extract.

Source

Thrown at resources/page/pagegroup.go:130

// GroupBy groups by the value in the given field or method name and with the given order.
// Valid values for order is asc, desc, rev and reverse.
func (p Pages) GroupBy(ctx context.Context, key string, order ...string) (PagesGroup, error) {
	if len(p) < 1 {
		return nil, nil
	}

	direction := "asc"

	if len(order) > 0 && (strings.ToLower(order[0]) == "desc" || strings.ToLower(order[0]) == "rev" || strings.ToLower(order[0]) == "reverse") {
		direction = "desc"
	}

	var ft any
	index := hreflect.GetMethodIndexByName(pagePtrType, key)
	if index != -1 {
		m := pagePtrType.Method(index)
		if m.Type.NumOut() == 0 || m.Type.NumOut() > 2 {
			return nil, errors.New(key + " is a Page method but you can't use it with GroupBy")
		}
		if m.Type.NumOut() == 1 && m.Type.Out(0).Implements(errorType) {
			return nil, errors.New(key + " is a Page method but you can't use it with GroupBy")
		}
		if m.Type.NumOut() == 2 && !m.Type.Out(1).Implements(errorType) {
			return nil, errors.New(key + " is a Page method but you can't use it with GroupBy")
		}
		ft = m
	} else {
		var ok bool
		ft, ok = pagePtrType.Elem().FieldByName(key)
		if !ok {
			return nil, errors.New(key + " is neither a field nor a method of Page")
		}
	}

	var tmp reflect.Value
	switch e := ft.(type) {

View on GitHub (pinned to 52c9bd7908)

Solutions

Group by a method that returns a single comparable value (e.g. "Section", "Type", "Date").
Verify the method's return signature in the Hugo Page API docs before using it as a GroupBy key.
If you need custom grouping logic, add the value as a page param and group by that param name.

Example fix

{{/* before: method returns nothing usable */}}
{{ .Pages.GroupBy "SomeVoidMethod" }}

{{/* after: group by a real scalar-returning method */}}
{{ .Pages.GroupBy "Section" }}

Defensive patterns

Strategy: validation

Prevention

Only group by methods returning one comparable value or (value, error).
Check the Page method's return arity before grouping.

When it happens

Trigger: Calling `{{ .Pages.GroupBy "SomeMethod" }}` where `SomeMethod` has a signature with no return values or more than two return values (e.g. a void setter method or a multi-tuple method).

Common situations: Grouping by a method not designed for grouping (a configurator/mutator); guessing a method name that resolves to an internal helper; version upgrades that change a method's arity.

Related errors

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