What causes "merge requires at least two parameters" in gohugoio/hugo?

Pass at least two maps: `{{ $merged := merge $defaults $overrides }}` (later maps in the call are merged into the last one; leftmost keys win).

gohugoio/hugo · error

merge requires at least two parameters

Error message

merge requires at least two parameters

What it means

`collections.Merge` deep-merges two or more maps, treating the last parameter as the base and merging preceding parameters into it in reverse order. Since merging is only meaningful with at least a source and a destination, Hugo returns this error when the function is called with fewer than two parameters.

Source

Thrown at tpl/collections/merge.go:32

package collections

import (
	"errors"
	"fmt"
	"reflect"
	"strings"

	"github.com/gohugoio/hugo/common/hmaps"
	"github.com/gohugoio/hugo/common/hreflect"
)

// Merge creates a copy of the final parameter in params and merges the preceding
// parameters into it in reverse order.
//
// Currently only maps are supported. Key handling is case insensitive.
func (ns *Namespace) Merge(params ...any) (any, error) {
	if len(params) < 2 {
		return nil, errors.New("merge requires at least two parameters")
	}

	var err error
	result := params[len(params)-1]

	for i := len(params) - 2; i >= 0; i-- {
		result, err = ns.merge(params[i], result)
		if err != nil {
			return nil, err
		}
	}

	return result, nil
}

// merge creates a copy of dst and merges src into it.
func (ns *Namespace) merge(src, dst any) (any, error) {
	vdst, vsrc := reflect.ValueOf(dst), reflect.ValueOf(src)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Pass at least two maps: `{{ $merged := merge $defaults $overrides }}` (later maps in the call are merged into the last one; leftmost keys win).
If one side may be empty, pass an empty dict explicitly: `{{ merge (default dict $maybe) $base }}`.
If you intended to construct a map rather than combine maps, use `dict` instead.

Example fix

<!-- before -->
{{ $opts := merge .Params }}
<!-- after -->
{{ $opts := merge site.Params.defaults .Params }}

Defensive patterns

Strategy: validation

Validate before calling

{{ $maps := slice $m1 $m2 }}
{{ if ge (len $maps) 2 }}{{ $merged := merge $m1 $m2 }}{{ end }}

Try / catch

{{ with try (merge $m1) }}{{ with .Err }}{{ warnf "merge needs >=2 maps: %s" . }}{{ else }}{{ .Value }}{{ end }}{{ end }}

Prevention

Always call merge with at least two map arguments; a single map has nothing to merge
When piping (`$m1 | merge $m2`), remember the piped value counts as the final argument — verify total is ≥2
If merging a dynamic list of maps, guard `len` ≥ 2 and fall back to the sole map yourself only if that behavior is explicitly desired

When it happens

Trigger: Calling `{{ merge $onlyOneMap }}` or `{{ merge }}` in a template; also a pipeline like `{{ $m | merge }}` where the pipe supplies the sole argument.

Common situations: Refactoring that removed one side of the merge; conditionally-built argument lists where a `with`/`if` left only one map in scope; confusion with `dict` (which builds a map from key/value pairs) versus `merge` (which combines existing maps).

Related errors

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