{"id":"55d682d9ad403614","repo":"gohugoio/hugo","slug":"unknown-dimension-q","errorCode":null,"errorMessage":"unknown dimension %q","messagePattern":"unknown dimension %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/sitesmatrix/dimensions.go","lineNumber":285,"sourceCode":"\tif vs == nil {\n\t\treturn nil\n\t}\n\treturn weightedVectorStore{VectorStore: vs, weight: weight}\n}\n\n// Dimension is a dimension in the Hugo build matrix.\ntype Dimension int8\n\nfunc ParseDimension(s string) (int, error) {\n\tswitch s {\n\tcase \"language\":\n\t\treturn Language, nil\n\tcase \"version\":\n\t\treturn Version, nil\n\tcase \"role\":\n\t\treturn Role, nil\n\tdefault:\n\t\treturn 0, fmt.Errorf(\"unknown dimension %q\", s)\n\t}\n}\n\nfunc DimensionName(d int) string {\n\tswitch d {\n\tcase Language:\n\t\treturn \"language\"\n\tcase Version:\n\t\treturn \"version\"\n\tcase Role:\n\t\treturn \"role\"\n\tdefault:\n\t\tpanic(\"unknown dimension\")\n\t}\n}\n\n// Common information provided by all of language, version and role.\ntype DimensionInfo interface {","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/sitesmatrix/dimensions.go#L267-L303","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Change the dimension name in your configuration to exactly one of: language, version, role.","Check for pluralization or casing typos (e.g. 'languages' → 'language').","If following external docs, confirm your installed Hugo version supports the sites-matrix dimensions you reference (hugo version)."],"exampleFix":"# before (hugo.toml)\n[matrix]\ndimensions = [\"languages\"]\n\n# after\n[matrix]\ndimensions = [\"language\"]","handlingStrategy":"validation","validationCode":"// Before building the site, verify each dimension name used in config/front matter\n// exists in the configured sites matrix.\nknown := map[string]bool{}\nfor _, d := range conf.SitesMatrix.Dimensions() { known[d.Name()] = true }\nif !known[dim] { return fmt.Errorf(\"dimension %q not configured\", dim) }","typeGuard":null,"tryCatchPattern":"if err := doBuild(); err != nil && strings.Contains(err.Error(), \"unknown dimension\") {\n    // report config error to the user; do not retry\n}","preventionTips":["Define all dimensions (e.g. languages/versions) in site config before referencing them in content or templates","Use a single source of truth (constants or config keys) for dimension names to avoid typos","Run a config-only validation build (hugo config / dry build) in CI to catch unknown dimensions early"],"tags":["hugo","configuration","sites-matrix","validation"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}