gohugoio/hugo · error

empty related config provided

Error message

empty related config provided

What it means

Returned by related.DecodeConfig in related/inverted_index.go:565 when the config map is non-nil but empty (len == 0). DecodeConfig expects at least threshold/indices configuration to build a meaningful related-content index.

Solutions

1. Either remove the empty [related] table (Hugo then uses defaults) or populate it with threshold and [[related.indices]].
2. Add a minimal index, e.g. threshold = 80 and an [[related.indices]] entry with name and type.
3. Validate the config with `hugo config` to confirm the related block is non-empty.

Example fix

// before
[related]
// after
[related]
threshold = 80
[[related.indices]]
name = "keywords"
weight = 100
type = "basic"

// Provide a non-empty related config or rely on defaults.
if len(relatedCfg) == 0 { /* omit [related] to use defaults, or populate it */ }

When it happens

Trigger: Providing an empty [related] table (e.g. `[related]` with no keys) in hugo.toml, or passing an empty non-nil map programmatically.

Common situations: Adding `[related]` to config as a placeholder but never filling it, or a config generator emitting an empty related map.

Related errors

• failed to decode related config
• invalid index type . Must be one of
• no related config provided
• related threshold must be between 0 and 100
• config needs a filename

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

Appendix: 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 52c9bd7908)