gohugoio/hugo · error

invalid number of arguments to ref

Error message

invalid number of arguments to ref

What it means

Thrown by refArgsToMap (tpl/urls/urls.go:143) when the arguments to ref/relref arrive as a []string slice whose length is 0 or greater than 2. ref accepts a path plus an optional outputFormat, so a slice must have 1 or 2 elements.

Solutions

1. Pass exactly one path string, or a slice of [path] or [path, outputFormat]
2. Use the map form for clarity: {{ ref . (dict "path" "foo" "outputFormat" "amp") }}
3. Validate the slice length before calling ref/relref

Example fix

// before
{{ ref . (slice "a.md" "amp" "extra") }}
// after
{{ ref . (dict "path" "a.md" "outputFormat" "amp") }}

if s, ok := args.([]string); ok && (len(s) == 0 || len(s) > 2) {
    return nil, fmt.Errorf("ref needs 1 or 2 string args, got %d", len(s))
}

When it happens

Trigger: Calling {{ ref . (slice) }} with an empty slice, or {{ ref . (slice "a" "b" "c") }} with three elements; passing a dynamically-built collection that yields too many items.

Common situations: Building the argument list programmatically and passing an empty collection; misunderstanding that ref takes at most path+outputFormat.

Related errors

• invalid Page received in Ref
• invalid Page received in RelRef
• error in Parse
• arg
• argument must be a slice

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

Appendix: source

Thrown at tpl/urls/urls.go:143

	)

	v := args
	if _, ok := v.([]any); ok {
		v = cast.ToStringSlice(v)
	}

	switch v := v.(type) {
	case map[string]any:
		return v, nil
	case map[string]string:
		m := make(map[string]any)
		for k, v := range v {
			m[k] = v
		}
		return m, nil
	case []string:
		if len(v) == 0 || len(v) > 2 {
			return nil, fmt.Errorf("invalid number of arguments to ref")
		}
		// These were the options before we introduced the map type:
		s = v[0]
		if len(v) == 2 {
			of = v[1]
		}
	default:
		var err error
		s, err = cast.ToStringE(args)
		if err != nil {
			return nil, err
		}

	}

	return map[string]any{
		"path":         s,
		"outputFormat": of,

View on GitHub (pinned to 52c9bd7908)