gohugoio/hugo · error

invalid Page received in Ref

Error message

invalid Page received in Ref

What it means

The urls.Ref template function type-asserts its first argument to urls.RefLinker (urls.go:94-96). Only Hugo Page objects satisfy this interface. When the value passed is not a Page (nil, string, .Site, .Params, a Resource, etc.), the assertion fails and this error is returned.

Solutions

1. Ensure the first argument is a Page object (use . in page context or an explicitly passed $page)
2. If inside a partial, pass the page in: {{ partial "myref.html" (dict "page" .) }} and call {{ ref .page "path" }}
3. Verify the template is evaluated in page context and not in a root/site-only context

Example fix

{{/* before: . is not a Page here */}}
{{ ref . "posts/my-post" }}
{{/* after: pass the page explicitly */}}
{{ ref $page "posts/my-post" }}

// In Go template code, check that the value is a Page before calling ref.
{{ with reflect.IsMap . }}{{ end }}
// In Go code:
func isRefLinker(v any) bool {
    _, ok := v.(urls.RefLinker)
    return ok
}

{{ if partial "is-page.html" . }}{{ ref . "path" }}{{ else }}{{ warnf "ref: not a page" }}{{ end }}

When it happens

Trigger: Calling {{ ref .SomeNonPage "path" }} or {{ ref .Site "path" }} where the first argument does not implement urls.RefLinker.

Common situations: Using ref inside a partial whose dot context is not a Page; passing .Params or .Site instead of the page; calling ref on a resource or taxonomy term object.

Related errors

• invalid Page received in RelRef
• invalid number of arguments to ref
• argument must be a slice
• arguments must be slices or arrays
• arguments to complement must be slices or arrays

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

Appendix: source

Thrown at tpl/urls/urls.go:96

	}
	return ns.deps.PathSpec.URLize(ss), nil
}

// Anchorize creates sanitized anchor name version of the string s that is compatible
// with how your configured markdown renderer does it.
func (ns *Namespace) Anchorize(s any) (string, error) {
	ss, err := cast.ToStringE(s)
	if err != nil {
		return "", err
	}
	return ns.deps.ContentSpec.SanitizeAnchorName(ss), nil
}

// 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

View on GitHub (pinned to 52c9bd7908)