gohugoio/hugo · error

failed to compile cascade target

Error message

failed to compile cascade target %d: %w

What it means

Returned by PageMatcherParamsConfigs.InitConfig when compileSitesMatrix fails for a specific cascade target. The %w wraps the underlying glob or sites-matrix compilation error, and %d is the zero-based index of the failing cascade entry. This runs during site initialization after all cascade config is decoded.

Solutions

1. Read the wrapped error for the specific compilation failure (e.g. invalid glob syntax).
2. Use the index %d in the error message to find the exact cascade entry in your config, then fix its target.sites.matrix block.
3. Verify that all language codes in sites.matrix.languages match languages defined under [languages] in hugo.toml.
4. If unsure about the sites.matrix syntax, remove it and use the simpler target approach, or consult the Hugo target documentation.

Example fix

# before (hugo.toml) — invalid language glob in sites.matrix
[cascade]
  [[cascade.target]]
    sites.matrix.languages = ["en", "fr", "xyz*"]
  [cascade.params]
    layout = "custom"

# after — use valid language codes or globs matching configured languages
[cascade]
  [[cascade.target]]
    sites.matrix.languages = ["en", "fr"]
  [cascade.params]
    layout = "custom"

// Validate sites.matrix configuration before InitConfig
func validateSitesMatrix(languages []string, configuredLangs []string) error {
    langSet := make(map[string]bool)
    for _, l := range configuredLangs {
        langSet[l] = true
    }
    for _, l := range languages {
        g, err := hglob.GetGlob(l)
        if err != nil {
            return fmt.Errorf("invalid language glob %q: %w", l, err)
        }
        _ = g // glob compilation itself is the common failure point
    }
    return nil
}

When it happens

Trigger: A cascade target with an invalid sites.matrix configuration — e.g. malformed glob patterns in the sites.matrix.languages field, or dimension values that the sitesmatrix builder cannot compile. The error identifies which cascade entry (by index) caused the failure.

Common situations: Setting target.sites.matrix.languages to an invalid glob or a language code that does not exist in the site's configured languages; migrating to the new sites.matrix API from the deprecated lang field with a syntax error; mismatched matrix dimension configuration.

Related errors

• failed to compile permalink target
• failed to decode sites from front matter
• key not allowed in cascade config
• did not match a valid Page Kind
• failed to init mount

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

Appendix: source

Thrown at resources/page/page_matcher.go:416

	}
	return h.Sum64()
}

func (c *PageMatcherParamsConfigs) InitConfig(logger loggers.Logger, defaultsIn sitesmatrix.VectorStore, configuredDimensions *sitesmatrix.ConfiguredDimensions) error {
	if c == nil {
		return nil
	}
	for _, cc := range c.c {
		for i := range cc.Config.Cascades {
			ccc := cc.Config.Cascades[i]
			checkCascadePattern(logger, ccc.Target)
			defaults := defaultsIn
			hasSitesMatrix := ccc.hasSitesMatrix()
			if hasSitesMatrix {
				defaults = nil
			}
			if err := ccc.Target.compileSitesMatrix(defaults, configuredDimensions); err != nil {
				return fmt.Errorf("failed to compile cascade target %d: %w", i, err)
			}
			cc.Config.Cascades[i] = ccc
		}
	}
	return nil
}

View on GitHub (pinned to 52c9bd7908)