gohugoio/hugo · error

failed to compile cascade target %d: %w

Error message

failed to compile cascade target %d: %w

What it means

`PageMatcherParamsConfigs.InitConfig` walks each configured cascade and compiles its `_target` sites matrix (languages and other site dimensions) against the site's configured dimensions. When `compileSitesMatrix` fails for cascade entry number `%d`, the error is wrapped with the cascade's index so you can find the offending block in an otherwise anonymous list. The wrapped `%w` cause carries the real reason, typically an unknown language or dimension value.

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 8a468df065)

Solutions

1. Read the wrapped cause after the colon — it names the specific dimension or value that failed to compile.
2. Use the index `%d` (zero-based) to locate the exact cascade entry in your config or front matter list.
3. Make the `_target` `lang` value exactly match a key under `[languages]` in your site config, including case and region suffix.
4. If the cascade comes from a theme/module, either define the missing language in your site config or override the cascade in your own config.
5. Run `hugo config` to dump the resolved languages and dimensions and diff them against the cascade targets.

Example fix

# before — site declares only [languages.en]
cascade:
  - _target:
      lang: en-US
    banner: hero.jpg

# after
cascade:
  - _target:
      lang: en
    banner: hero.jpg

// pre-validate each cascade entry's _target globs
for i, t := range cascadeTargets {
    if _, err := glob.Compile(t.Path); err != nil {
        return fmt.Errorf("cascade target %d has bad path glob %q: %w", i, t.Path, err)
    }
}

if err := site.Build(); err != nil {
    var e *herrors.ErrorWithFileContext
    if errors.As(err, &e) {
        // config error: report file + cascade index from the wrapped message
    }
    return err
}

When it happens

Trigger: Defining `[[cascade]]` entries whose `_target` includes `lang`/`languages` or other sites-matrix dimensions that are not among the site's configured dimensions; also triggered when a cascade sets a sites matrix that conflicts with the defaults for a multilingual or multi-dimension site setup.

Common situations: Targeting a language code that isn't in `[languages]` (e.g. `lang: en-US` when the site declares `en`); a theme or module contributing a cascade for a language the consuming site doesn't define; adding a new site dimension in config but not to every cascade target after upgrading to a Hugo release with the sites-matrix model.

Related errors

• failed to decode languages config: %w
• failed to create config: %w
• invalid language configuration for %q
• failed to decode config for language %q: %w
• language name cannot be empty

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/021de5ae95e4c970.json. Report an issue: GitHub ↗.