What causes "page reference %q is ambiguous" in gohugoio/hugo?

Use a more specific path in the ref: `{{ }}` instead of `{{ }}`.

page reference is ambiguous

Error message

page reference %q is ambiguous

What it means

Raised by getContentNodeForRef (pagecollections.go:218) during a simple (no-slash) ref lookup when the pageReverseIndex returns the ambiguousContentNode sentinel. That sentinel is set when two or more distinct content nodes share the same base-name-without-identifier, so a bare name like {{< ref "about" >}} cannot be resolved to a single page.

Solutions

Use a more specific path in the ref: `{{< ref "/company/about.md" >}}` instead of `{{< ref "about" >}}`.
Rename one of the colliding files so the base name is unique.
If the duplicate is unintentional, delete or move the redundant content file.

Example fix

{{/* before */}}
{{< ref "about" >}}

{{/* after */}}
{{< ref "/company/about.md" >}}

Defensive patterns

Strategy: validation

Validate before calling

# Detect base-name collisions across content files before building.
find content -type f \( -name '*.md' -o -name '*.adoc' \) -printf '%f\n' | sort | uniq -d

Prevention

Always use fully qualified paths in refs ({{< ref "/section/page.md" >}}) to avoid ambiguity.
Keep content file base names unique across the project.
Periodically run the collision check above in CI.

When it happens

Trigger: Two files named about.md in different sections; a content file and a branch bundle sharing a base name; using a bare filename ref (no path) where multiple pages collide on that name. Only triggers for refs with zero slashes (doSimpleLookup at line 209).

Common situations: Multilingual content where the same slug exists per language but lookup crosses languages; an about.md at content root and another in a section; renaming files such that base names now clash.

Related errors

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

Appendix: source

Thrown at hugolib/pagecollections.go:218

	if hadExtension && s.home != nil && s.home.File() != nil {
		if n, err := c.getContentNodeFromRefReverseLookup(inRef, s.home.File().FileInfo()); n != nil || err != nil {
			return n, err
		}
	}

	var doSimpleLookup bool
	if isReflink || context == nil {
		slashCount := strings.Count(inRef, "/")
		doSimpleLookup = slashCount == 0
	}

	if !doSimpleLookup {
		return nil, nil
	}

	n = c.pm.pageReverseIndex.Get(nameNoIdentifier)
	if n == ambiguousContentNode {
		return nil, fmt.Errorf("page reference %q is ambiguous", inRef)
	}

	return n, nil
}

func (c *pageFinder) getContentNodeFromRefReverseLookup(ref string, fi hugofs.FileMetaInfo) (contentNode, error) {
	s := c.pm.s
	meta := fi.Meta()
	dir := meta.Filename
	if !fi.IsDir() {
		dir = filepath.Dir(meta.Filename)
	}

	realFilename := filepath.Join(dir, ref)

	pcs, err := s.BaseFs.Content.ReverseLookup(realFilename, true)
	if err != nil {
		return nil, err

View on GitHub (pinned to 52c9bd7908)