gohugoio/hugo · error

unknown dimension

Error message

unknown dimension %q

What it means

ParseDimension converts a string dimension name into its integer constant; only "language", "version", and "role" are valid (sitesmatrix.Language/Version/Role). Any other string reaches the default branch and returns this error. This is an internal API used when configuring the build matrix dimensions from string config or query input.

Solutions

1. Correct the dimension string to one of: language, version, role.
2. If accepting user/config input, validate against this allowlist before calling ParseDimension.
3. Use DimensionName/Dimension constants instead of raw strings where possible to avoid typos.

Example fix

// before
d, err := sitesmatrix.ParseDimension("languages") // typo/unknown

// after
d, err := sitesmatrix.ParseDimension("language")

var validDimensions = map[string]bool{"language": true, "version": true, "role": true}

func safeParseDimension(s string) (int, error) {
    if !validDimensions[s] {
        return 0, fmt.Errorf("unknown dimension %q (want language|version|role)", s)
    }
    return sitesmatrix.ParseDimension(s)
}

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

When it happens

Trigger: Calling sitesmatrix.ParseDimension with a typo'd or unsupported name such as "languages", "lang", "outputFormat", or "kind". Typically arises from malformed config deserialization or a code path passing a user string directly.

Common situations: Custom code or a config key that names a dimension with the wrong token; a Hugo upgrade that renamed/added a dimension while consuming code kept the old name; integration tests feeding arbitrary strings.

Related errors

• aligny must be one of top, center, bottom
• cardinalityThreshold threshold must be between 0 and 100
• config needs a filename
• empty path is reserved for the home page
• failed to apply filters

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

Appendix: 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 52c9bd7908)