gohugoio/hugo · error

failed to compile permalink target

Error message

failed to compile permalink target %d: %w

What it means

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.

Solutions

1. Read the wrapped error to find the unknown dimension identifier in the permalink target's sites config.
2. Ensure every language/role/version referenced in the permalink target exists in your configured dimensions.
3. Remove the 'sites' block from the target if per-site permalinks are not needed.

Example fix

# before
[[permalinks]]
target = { kind = "page", path = "/posts/**", sites = { matrix = { language = "zz" } } }
pattern = "/:year/:slug/"
# after (use a configured language)
[[permalinks]]
target = { kind = "page", path = "/posts/**", sites = { matrix = { language = "en" } } }
pattern = "/:year/:slug/"

for i, c := range configs {
    if err := c.Target.compileSitesMatrix(nil, dims); err != nil {
        return fmt.Errorf("permalink %d sites invalid: %w", i, err)
    }
}

if err := configs.InitConfig(logger, base, dims); err != nil {
    return fmt.Errorf("permalinks init: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to decode sites from front matter
• failed to compile cascade target
• failed to init mount
• permalink attribute not recognised
• permalinks configuration not supported for kind

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

Appendix: source

Thrown at resources/page/permalinks.go:50

	"github.com/gohugoio/hugo/resources/kinds"
	"github.com/mitchellh/mapstructure"
)

// PermalinkConfig holds a single permalink rule with a target matcher and a pattern.
type PermalinkConfig struct {
	Target  PageMatcher
	Pattern string
}

// PermalinksConfig is an ordered slice of permalink rules.
// For any given Page, the first matching rule wins.
type PermalinksConfig []PermalinkConfig

// InitConfig compiles the sites matrix for each permalink target.
func (c PermalinksConfig) InitConfig(logger loggers.Logger, defaultSitesMatrix sitesmatrix.VectorStore, configuredDimensions *sitesmatrix.ConfiguredDimensions) error {
	for i := range c {
		if err := c[i].Target.compileSitesMatrix(nil, configuredDimensions); err != nil {
			return fmt.Errorf("failed to compile permalink target %d: %w", i, err)
		}
	}
	return nil
}

// PermalinkExpander holds permalink mappings.
type PermalinkExpander struct {
	// knownPermalinkAttributes maps :tags in a permalink specification to a
	// function which, given a page and the tag, returns the resulting string
	// to be used to replace that tag.
	knownPermalinkAttributes map[string]pageToPermaAttribute

	configs PermalinksConfig

	urlize func(uri string) string

	patternCache *hmaps.Cache[string, func(Page) (string, error)]
}

View on GitHub (pinned to 52c9bd7908)