gohugoio/hugo · error
failed to parse dimension %q: %w
Error message
failed to parse dimension %q: %w
What it means
Returned by pageState.Rotate when the dimension string passed to it cannot be parsed by sitesmatrix.ParseDimension. Rotate returns all variants of a page along one axis of Hugo's sites matrix (e.g. language), and the dimension argument must name a known matrix dimension; anything else is rejected with the parse error wrapped.
Source
Thrown at hugolib/page.go:540
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 8a468df065)
Solutions
- Pass a valid dimension name recognized by sitesmatrix.ParseDimension (see sitesmatrix package / Hugo docs for the sites matrix, e.g. "language").
- If the dimension comes from a variable, validate it or guard the call with `with` before invoking .Rotate.
- Confirm your Hugo version supports the sites-matrix dimension you're using; upgrade if it was added later.
Example fix
<!-- before -->
{{ range .Rotate "lang" }}...{{ end }}
<!-- after -->
{{ range .Rotate "language" }}...{{ end }} Defensive patterns
Strategy: validation
Validate before calling
// Front matter images/videos dimension strings must be WxH integers
// e.g. "1200x630" — validate before committing content:
re := regexp.MustCompile(`^\d+x\d+$`)
if !re.MatchString(dim) {
return fmt.Errorf("bad dimension %q, want WIDTHxHEIGHT", dim)
} Prevention
- Write dimensions as integer WIDTHxHEIGHT (e.g. 1200x630) with a lowercase x and no units or spaces
- Validate front matter in CI (archetype or schema check) so malformed dimensions fail before a build
- Don't template dimension values from variables that may be empty
When it happens
Trigger: Calling `.Rotate "<dim>"` from a template (or the API) with a string that ParseDimension rejects — a misspelled or unsupported dimension name; the input is lowercased first, so it's the name itself that is wrong, not casing.
Common situations: Guessing dimension names (e.g. "lang" vs "language"), using a dimension from a newer Hugo version's sites-matrix feature on an older release, or passing a page/front-matter variable that is empty or holds the wrong value.
Related errors
- errKeyIsEmptyString
- %q is not a valid duration unit
- errMustTwoNumbersError
- strings: negative Repeat count
- error correction level must be one of low, medium, quartile,
AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31).
Data as JSON: /data/errors/9ddff25266f9636b.json.
Report an issue: GitHub ↗.