gohugoio/hugo · error

unknown dimension %q

Error message

unknown dimension %q

What it means

Panic in Site.Dimension(d): the dimension name d is not one of the recognized names ('language', 'version', 'role'). Dimension exposes a single site-axis value for use in templates (e.g. in a sites matrix); an unknown name is a caller/template error.

Source

Thrown at hugolib/site.go:635

	h.init.gitInfo = hsync.OnceMoreFunc(func(ctx context.Context) error {
		return h.loadGitInfo()
	})

	return h, nil
}

// GetSiteDimension returns the value of the specified site dimension (such as language, version, or role)
// based on the provided dimension name string. If the dimension name is unknown, it panics.
func (s *Site) Dimension(d string) page.SiteDimension {
	switch d {
	case sitesmatrix.DimensionName(sitesmatrix.Language):
		return s.language
	case sitesmatrix.DimensionName(sitesmatrix.Version):
		return s.version
	case sitesmatrix.DimensionName(sitesmatrix.Role):
		return s.role
	default:
		panic(fmt.Sprintf("unknown dimension %q", d))
	}
}

// Returns the server port.
func (s *Site) ServerPort() int {
	return s.conf.C.BaseURL.Port()
}

// Returns the configured title for this Site.
func (s *Site) Title() string {
	return s.conf.Title
}

func (s *Site) Copyright() string {
	return s.conf.Copyright
}

func (s *Site) Lang() string {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Use only valid dimension names: "language", "version", or "role".
2. If you only need the language, prefer .Language or .Lang instead of .Dimension.
3. Check the sitesmatrix config; enable the version/role dimension before querying it.

Example fix

{{/* before */}}
{{ .Site.Dimension "lang" }}

{{/* after */}}
{{ .Site.Dimension "language" }}
{{/* or simpler */}} {{ .Site.Language.Lang }}

// Whitelist dimension names before calling .Dimension.
// Template:  {{ in (slice "language" "version" "role") $d }}
// Go:        var validDim = map[string]bool{"language":true,"version":true,"role":true}

func validDimension(d string) bool {
    switch d {
    case "language", "version", "role":
        return true
    }
    return false
}

// Usage: if validDimension(d) { v := site.Dimension(d) }

When it happens

Trigger: Calling .Site.Dimension "<invalid>" or sitesmatrix dimension lookups with a typo'd or unsupported name. The valid names come from sitesmatrix.DimensionName of Language, Version, Role. Passing 'lang', 'locale', 'env', etc. triggers the panic.

Common situations: Template author guesses a dimension name. Using a feature (e.g. versions/roles) without enabling it and passing a name. Typo in a dimension string.

Related errors

• too many arguments, expected 0 or 1
• alignx must be one of left, center, right
• Shifter is required
• transformerRaw is required
• Transform must be performed with NoShift=true

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