{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/page/permalinks.go#L32-L68","documentation":"PermalinksConfig.InitConfig runs at config load and compiles the sites-matrix matcher (target selector) for each configured permalink rule. If a rule's Target cannot be compiled against the configured dimensions (languages/roles/versions), config initialization fails with this error, wrapping the underlying compile error and reporting the zero-based rule index.","triggerScenarios":"Starting a build with a `permalinks` config using the structured target form where the target matcher references invalid values — e.g. a language, role, or version dimension value not present in the site's configured dimensions, or a malformed matcher expression.","commonSituations":"Multilingual configs where a permalink rule targets a language code that was removed or renamed; typos in dimension values; upgrading to a Hugo version with the sites-matrix model and carrying over stale target definitions.","solutions":["Look at rule index N (zero-based) in your `permalinks` config and fix the target matcher named in the wrapped error.","Ensure every dimension value referenced (language, etc.) exists in the site configuration exactly as spelled.","Simplify to the plain `permalinks: { posts: \"/:year/:slug/\" }` form if you don't need per-target matching."],"exampleFix":"# before (hugo.toml) — 'nn' not a configured language\n[[permalinks.config]]\n  [permalinks.config.target]\n    lang = 'nn'\n  pattern = '/:slug/'\n# after\n  [permalinks.config.target]\n    lang = 'nb'","handlingStrategy":"validation","validationCode":"// Sanity-check permalink patterns from config before site build\nfor kind, pattern := range permalinksConfig {\n    if !strings.HasPrefix(pattern, \"/\") {\n        return fmt.Errorf(\"permalink for %q must start with '/': %q\", kind, pattern)\n    }\n    if strings.Contains(pattern, \"::\") || strings.HasSuffix(pattern, \":\") {\n        return fmt.Errorf(\"malformed attribute in permalink %q\", pattern)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to compile permalink\") {\n    // bad pattern in [permalinks] config — fix the pattern, don't ignore\n}","preventionTips":["Start every permalink pattern with '/' and use only documented :attributes","Run a build in CI whenever site config changes so pattern errors surface early","Keep permalink patterns simple; avoid hand-built dynamic patterns"],"tags":["hugo","permalinks","config","multilingual"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}