gohugoio/hugo · error

failed to parse dimension

Error message

failed to parse dimension %q: %w

What it means

Raised by pageState.Rotate (page.go:535) when sitesmatrix.ParseDimension cannot map the supplied dimension string. ParseDimension only accepts the known dimension names — 'language', 'version', 'role' (see sitesmatrix/dimensions.go). Anything else makes Rotate fail before it can walk the page tree.

Solutions

1. Use one of the supported dimension names: "language", "version", or "role".
2. Check for typos — the string is lowercased but must still match exactly.
3. If the value is dynamic, validate it against the allow-list before calling Rotate.

Example fix

// before
{{ range .Rotate "output" }}...{{ end }}

// after
{{ range .Rotate "language" }}...{{ end }}

// allow-list the Rotate dimension before calling
var allowedDim = map[string]bool{"language": true, "version": true, "role": true}
// if !allowedDim[dim] { return fmt.Errorf("unsupported dimension %q", dim) }

When it happens

Trigger: Calling `.Rotate` on a page in a template with an argument that isn't one of the supported dimensions, e.g. `{{ .Rotate "output" }}` or a typo like `{{ .Rotate "langauge" }}`. The value is lowercased first, but casing isn't the issue — vocabulary is.

Common situations: Misremembering the dimension name; guessing 'output'/'format' instead of the real names; passing a user-controlled string into Rotate without validation.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• alignx must be one of left, center, right
• can't apply the operator to the values
• Defer does not take any arguments
• error building site
• Error creating WebPAnimEncoder\n

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

Appendix: source

Thrown at hugolib/page.go:535

func (ps *pageState) SiteVector() sitesmatrix.Vector {
	return ps.s.siteVector
}

func (ps *pageState) siteVector() sitesmatrix.Vector {
	return ps.s.siteVector
}

func (ps *pageState) siteVectors() sitesmatrix.VectorIterator {
	return ps.s.siteVector
}

// Rotate returns all pages in the given dimension for this page.
func (ps *pageState) Rotate(dimensionStr string) (page.Pages, error) {
	dimensionStr = strings.ToLower(dimensionStr)
	key := ps.Path() + "/" + "rotate-" + dimensionStr
	d, err := sitesmatrix.ParseDimension(dimensionStr)
	if err != nil {
		return nil, fmt.Errorf("failed to parse dimension %q: %w", dimensionStr, err)
	}

	pages, err := ps.s.pageMap.getOrCreatePagesFromCache(ps.s.pageMap.cachePages2, key, func(string) (page.Pages, error) {
		var pas page.Pages
		ps.s.pageMap.treePages.ForEeachInDimension(ps.Path(), ps.s.siteVector, d,
			func(n contentNode) bool {
				if n != nil {
					p := n.(page.Page)
					pas = append(pas, p)
				}
				return true
			},
		)

		if dimensionStr == "language" && ps.m.pageConfig.TranslationKey != "" {
			// translationKey set by user.
			// This is an old construct back from when languages were introduced.
			// We keep it for backward compatibility.

View on GitHub (pinned to 52c9bd7908)