gohugoio/hugo · error

empty related config provided

Error message

empty related config provided

What it means

Companion check to error 506: `DecodeConfig` also rejects a non-nil but zero-length params map (related/inverted_index.go:564). An empty `related = {}` block would silently disable related content with no indices, so Hugo fails fast to force either a real configuration or removal of the section (defaults apply when the section is absent).

Source

Thrown at related/inverted_index.go:565

	return result, nil
}

// normalizes num to a number between 0 and 100.
func norm(num, min, max int) int {
	if min > max {
		panic("min > max")
	}
	return int(math.Floor((float64(num-min) / float64(max-min) * 100) + 0.5))
}

// DecodeConfig decodes a slice of map into Config.
func DecodeConfig(m hmaps.Params) (Config, error) {
	if m == nil {
		return Config{}, errors.New("no related config provided")
	}

	if len(m) == 0 {
		return Config{}, errors.New("empty related config provided")
	}

	var c Config

	if err := mapstructure.WeakDecode(m, &c); err != nil {
		return c, err
	}

	if c.Threshold < 0 || c.Threshold > 100 {
		return Config{}, errors.New("related threshold must be between 0 and 100")
	}

	if c.ToLower {
		for i := range c.Indices {
			c.Indices[i].ToLower = true
		}
	}
	for i := range c.Indices {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Delete the empty `related` section so Hugo uses its default related config (keywords + date indices).
2. Or fill the section with at least the settings you want, e.g. `threshold` and one `indices` entry.

Example fix

# before (hugo.toml)
[related]
# after
[related]
threshold = 80
[[related.indices]]
name = "keywords"
weight = 100

# An empty [related] table removes the defaults — declare at least one index
[related]
  threshold = 80
  [[related.indices]]
    name = "keywords"
    weight = 100

func configPopulated(cfg related.Config) bool { return len(cfg.Indices) > 0 }

if err := validate(cfg); err != nil {
    return fmt.Errorf("[related] declared but has no indices — remove the table to use defaults, or add indices: %w", err)
}

When it happens

Trigger: Calling related.DecodeConfig with an empty hmaps.Params — a `[related]` / `related: {}` section in site config that contains no keys.

Common situations: Adding an empty `[related]` table in hugo.toml as a placeholder; commenting out all keys inside the section but leaving the header; templating/merging config that produces `related: {}`.

Related errors

• failed to decode related config: %w
• no related config provided
• invalid index type %q. Must be one of %v
• cardinalityThreshold threshold must be between 0 and 100
• language %q not found

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