What causes "invalid arguments to Ref: %w" in gohugoio/hugo?

Pass a properly typed map to .Ref, e.g. `.Ref (dict "path" "posts/a.md" "lang" "en")`.

invalid arguments to Ref

Error message

invalid arguments to Ref: %w

What it means

Returned by pageRef.ref (page__ref.go:79) when decodeRefArgs fails to WeakDecode the arguments map into refArgs {Path, Lang, OutputFormat}. This is the .Ref / refLink path used by the ref and relref shortcodes and the .Ref method on pages.

Solutions

Pass a properly typed map to .Ref, e.g. `.Ref (dict "path" "posts/a.md" "lang" "en")`.
When using the ref/relref shortcode, use the documented path string form: `{{< ref "posts/a.md" >}}`.
Ensure Lang and OutputFormat values are strings and Path is present.

Example fix

{{/* before */}}
{{ .Ref .File.Dir }}

{{/* after */}}
{{ .Ref (dict "path" "posts/a.md") }}

Defensive patterns

Strategy: validation

Type guard

{{/* Type-guard .Ref args before calling */}}
{{ $args := .Params.refargs }}
{{ if and (reflect.IsMap $args) (index $args "path") }}
  {{ .Ref $args }}
{{ else }}
  {{ warnf ".Ref needs a map with a string 'path'" }}
{{ end }}

Prevention

Standardize on the map form (dict "path" "...") for .Ref across the project.
Keep Lang/OutputFormat values as strings; avoid passing computed non-string values.
Prefer the {{< ref "path" >}} shortcode for simple cases — Hugo validates its args.

When it happens

Trigger: Passing .Ref a value that is not a map (e.g. a bare string when a map is expected in the new API); a field with the wrong type (e.g. Lang as an int); malformed arguments from a hand-written {{< ref >}} invocation.

Common situations: Mixing the old positional ref shortcode style with the new map style; passing `.File.Dir` (string) where `.Ref` expects a map; typos like `langs` instead of `lang` combined with a non-string value.

Related errors

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

Appendix: source

Thrown at hugolib/page__ref.go:79

			if ss.Lang() == ra.Lang {
				found = true
				s = ss
			}
		}

		if !found {
			p.p.s.siteRefLinker.logNotFound(ra.Path, fmt.Sprintf("no site found with lang %q", ra.Lang), nil, text.Position{})
			return ra, nil, nil
		}
	}

	return ra, s, nil
}

func (p pageRef) ref(argsm map[string]any, source any) (string, error) {
	args, s, err := p.decodeRefArgs(argsm)
	if err != nil {
		return "", fmt.Errorf("invalid arguments to Ref: %w", err)
	}

	if s == nil {
		return p.p.s.siteRefLinker.notFoundURL, nil
	}

	if args.Path == "" {
		return "", nil
	}

	return s.siteRefLinker.refLink(args.Path, source, false, args.OutputFormat)
}

func (p pageRef) relRef(argsm map[string]any, source any) (string, error) {
	args, s, err := p.decodeRefArgs(argsm)
	if err != nil {
		return "", fmt.Errorf("invalid arguments to Ref: %w", err)
	}

View on GitHub (pinned to 52c9bd7908)