gohugoio/hugo · error

invalid Page received in RelRef

Error message

invalid Page received in RelRef

What it means

Identical to the Ref case but for `relref`: the first argument must be a Page implementing the RefLinker interface so Hugo can resolve a relative URL from that page's position. A non-Page first argument (string, dict, nil) triggers this error immediately.

Source

Thrown at tpl/urls/urls.go:110

// Ref returns the absolute URL path to a given content item from Page p.
func (ns *Namespace) Ref(p any, args any) (string, error) {
	pp, ok := p.(urls.RefLinker)
	if !ok {
		return "", errors.New("invalid Page received in Ref")
	}
	argsm, err := ns.refArgsToMap(args)
	if err != nil {
		return "", err
	}
	s, err := pp.Ref(argsm)
	return s, err
}

// RelRef returns the relative URL path to a given content item from Page p.
func (ns *Namespace) RelRef(p any, args any) (string, error) {
	pp, ok := p.(urls.RefLinker)
	if !ok {
		return "", errors.New("invalid Page received in RelRef")
	}
	argsm, err := ns.refArgsToMap(args)
	if err != nil {
		return "", err
	}

	s, err := pp.RelRef(argsm)
	return s, err
}

func (ns *Namespace) refArgsToMap(args any) (map[string]any, error) {
	var (
		s  string
		of string
	)

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

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Pass the Page explicitly: `{{ relref page "about.md" }}` or `{{ relref .Page "about.md" }}` in shortcodes.
2. When calling partials, thread the Page through the dict and use it as relref's first argument.
3. If you only need a link in content files, use the `relref` shortcode (`{{% raw %}}{{< relref "about.md" >}}{{% /raw %}}`), which supplies the page automatically.

Example fix

{{/* before, in a partial with dict context */}}
{{ relref . "docs/setup.md" }}
{{/* after */}}
{{ relref .page "docs/setup.md" }}{{/* where .page was passed in the dict */}}

{{ with .Page }}{{ relref . "/blog/post" }}{{ end }}

{{/* ensure the dot is a Page before relref */}}
{{ with $.Page }}{{ $url := relref . "/docs/intro" }}{{ end }}

{{ with try (relref $page "/docs/intro") }}
  {{ with .Err }}{{ warnf "relref failed: %s" . }}{{ end }}
{{ end }}

When it happens

Trigger: `{{ relref "about.md" }}`-style calls missing the page argument, `{{ relref . "x" }}` inside a shortcode or partial where `.` is not a Page, or passing a params dict as the context.

Common situations: Shortcodes using `.` instead of `.Page`; partials called with a custom dict that loses the Page; templates ported from docs examples that assumed a page context; theme partials invoked from non-page contexts like 404 or taxonomy edge cases.

Related errors

• invalid Page received in Ref
• invalid arguments to Ref: %w
• error building site: %w
• failed to detect format from content
• failed to detect target data serialization format

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