gohugoio/hugo · error

unknown dimension %q

Error message

unknown dimension %q

What it means

Raised by ParseDimension in hugolib/sitesmatrix/dimensions.go:285 when a string does not name one of Hugo's build-matrix dimensions. Hugo's sites matrix recognizes exactly three dimensions — "language", "version", and "role" — and any other string is rejected so misconfigured dimension references fail fast instead of silently building the wrong site variants.

Source

Thrown at hugolib/sitesmatrix/dimensions.go:285

	if vs == nil {
		return nil
	}
	return weightedVectorStore{VectorStore: vs, weight: weight}
}

// Dimension is a dimension in the Hugo build matrix.
type Dimension int8

func ParseDimension(s string) (int, error) {
	switch s {
	case "language":
		return Language, nil
	case "version":
		return Version, nil
	case "role":
		return Role, nil
	default:
		return 0, fmt.Errorf("unknown dimension %q", s)
	}
}

func DimensionName(d int) string {
	switch d {
	case Language:
		return "language"
	case Version:
		return "version"
	case Role:
		return "role"
	default:
		panic("unknown dimension")
	}
}

// Common information provided by all of language, version and role.
type DimensionInfo interface {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Change the dimension name in your configuration to exactly one of: language, version, role.
2. Check for pluralization or casing typos (e.g. 'languages' → 'language').
3. If following external docs, confirm your installed Hugo version supports the sites-matrix dimensions you reference (hugo version).

Example fix

# before (hugo.toml)
[matrix]
dimensions = ["languages"]

# after
[matrix]
dimensions = ["language"]

// Before building the site, verify each dimension name used in config/front matter
// exists in the configured sites matrix.
known := map[string]bool{}
for _, d := range conf.SitesMatrix.Dimensions() { known[d.Name()] = true }
if !known[dim] { return fmt.Errorf("dimension %q not configured", dim) }

if err := doBuild(); err != nil && strings.Contains(err.Error(), "unknown dimension") {
    // report config error to the user; do not retry
}

When it happens

Trigger: Calling ParseDimension with any string other than "language", "version", or "role" — typically from site configuration that references a dimension by name (e.g. matrix/dimension keys in hugo.toml) or internal callers resolving a dimension from user input.

Common situations: Typos in configuration such as "languages" (plural), "lang", "versions", or "roles"; using a dimension name from an older/newer Hugo release or third-party docs; case issues, since the match is exact lowercase; hand-edited config after upgrading to a Hugo version with the sites-matrix feature.

Related errors

• invalid deployment.target.include %q: %v
• invalid deployment.target.exclude %q: %v
• empty deployment target
• failed to parse dimension %q: %w
• redirects must have either From or FromRe set

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/55d682d9ad403614.json. Report an issue: GitHub ↗.