gohugoio/hugo · error

invalid number of arguments to ref

Error message

invalid number of arguments to ref

What it means

Hugo's `ref`/`relref` template functions accept either a page path string, a map of options, or a legacy string slice of 1–2 elements (path and optional output format). This error is raised in `refArgsToMap` when the arguments are passed as a slice that is empty or has more than two elements, so Hugo cannot map them to a path and output format.

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 8a468df065)

Solutions

1. Pass a plain string: `{{ ref . "/blog/my-post.md" }}`.
2. If you need an output format, use exactly two slice elements: `{{ ref . (slice "my-post" "amp") }}`.
3. Prefer the map form for options: `{{ ref . (dict "path" "my-post" "outputFormat" "amp") }}`.
4. If the slice is built dynamically, guard against it being empty before calling ref.

Example fix

<!-- before -->
{{ ref . (slice "my-post" "amp" "en") }}
<!-- after -->
{{ ref . (dict "path" "my-post" "outputFormat" "amp" "lang" "en") }}

{{/* ref takes the page plus one options/path argument — build args explicitly */}}
{{ $path := "/docs/install.md" }}
{{ with $path }}{{ ref $ . }}{{ end }}

When it happens

Trigger: Calling `{{ ref . (slice) }}` or `{{ ref . (slice "about" "html" "extra") }}` — i.e. passing a `[]string`/`[]any` with 0 or 3+ elements to `ref`, `relref`, or the corresponding page methods `.Ref`/`.RelRef`.

Common situations: Templates written for the old two-argument slice form that accidentally append extra values; building the argument slice dynamically from front matter and it comes out empty; confusing the slice form with the newer options-map form.

Related errors

• invalid arguments to Ref: %w
• need at least 2 arguments to append
• must provide a Resource and optionally an options map
• operator argument must be string type
• can't evaluate the array by no match argument or more than o

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