{"record":{"id":"bcb998527a50c012","repo":"gohugoio/hugo","slug":"failed-to-compile-permalink-target-d-w","errorCode":null,"errorMessage":"failed to compile permalink target %d: %w","messagePattern":"failed to compile permalink target (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/page/permalinks.go","lineNumber":50,"sourceCode":"\t\"github.com/gohugoio/hugo/resources/kinds\"\n\t\"github.com/mitchellh/mapstructure\"\n)\n\n// PermalinkConfig holds a single permalink rule with a target matcher and a pattern.\ntype PermalinkConfig struct {\n\tTarget  PageMatcher\n\tPattern string\n}\n\n// PermalinksConfig is an ordered slice of permalink rules.\n// For any given Page, the first matching rule wins.\ntype PermalinksConfig []PermalinkConfig\n\n// InitConfig compiles the sites matrix for each permalink target.\nfunc (c PermalinksConfig) InitConfig(logger loggers.Logger, defaultSitesMatrix sitesmatrix.VectorStore, configuredDimensions *sitesmatrix.ConfiguredDimensions) error {\n\tfor i := range c {\n\t\tif err := c[i].Target.compileSitesMatrix(nil, configuredDimensions); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to compile permalink target %d: %w\", i, err)\n\t\t}\n\t}\n\treturn nil\n}\n\n// PermalinkExpander holds permalink mappings.\ntype PermalinkExpander struct {\n\t// knownPermalinkAttributes maps :tags in a permalink specification to a\n\t// function which, given a page and the tag, returns the resulting string\n\t// to be used to replace that tag.\n\tknownPermalinkAttributes map[string]pageToPermaAttribute\n\n\tconfigs PermalinksConfig\n\n\turlize func(uri string) string\n\n\tpatternCache *hmaps.Cache[string, func(Page) (string, error)]\n}","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/page/permalinks.go#L32-L68","documentation":"Thrown by PermalinksConfig.InitConfig while compiling the sites matrix for each permalink target's PageMatcher via compileSitesMatrix. The index in the message is the zero-based position of the failing rule in the permalinks config; the wrapped error is the sites-matrix compile failure.","triggerScenarios":"A permalink rule's 'target' sets a 'sites' matrix with invalid dimension globs (e.g. an unknown language/role/version identifier, or malformed glob syntax) so the sites matrix cannot be compiled at startup.","commonSituations":"Configuring permalinks per-site in a multilingual/multi-dimension setup and referencing a language or dimension that is not configured, or a typo in the sites glob.","solutions":["Read the wrapped error to find the unknown dimension identifier in the permalink target's sites config.","Ensure every language/role/version referenced in the permalink target exists in your configured dimensions.","Remove the 'sites' block from the target if per-site permalinks are not needed."],"exampleFix":"# before\n[[permalinks]]\ntarget = { kind = \"page\", path = \"/posts/**\", sites = { matrix = { language = \"zz\" } } }\npattern = \"/:year/:slug/\"\n# after (use a configured language)\n[[permalinks]]\ntarget = { kind = \"page\", path = \"/posts/**\", sites = { matrix = { language = \"en\" } } }\npattern = \"/:year/:slug/\"","handlingStrategy":"validation","validationCode":"for i, c := range configs {\n    if err := c.Target.compileSitesMatrix(nil, dims); err != nil {\n        return fmt.Errorf(\"permalink %d sites invalid: %w\", i, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := configs.InitConfig(logger, base, dims); err != nil {\n    return fmt.Errorf(\"permalinks init: %w\", err)\n}","preventionTips":["Reference only configured languages/roles/versions in permalink target sites.","Validate sites globs against configured dimensions.","Drop the 'sites' block when per-site permalinks are unnecessary."],"tags":["hugo","permalinks","sites-matrix","multilingual","configuration"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}