gohugoio/hugo · error

related threshold must be between 0 and 100

Error message

related threshold must be between 0 and 100

What it means

After decoding the `related` config, Hugo validates that `threshold` — the minimum normalized match rank (0–100) a candidate page needs to count as related — lies in range (related/inverted_index.go:574). Values outside 0–100 are meaningless since ranks are normalized to that scale by norm().

Source

Thrown at related/inverted_index.go:575

// 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 {
		// Lower case name.
		c.Indices[i].Name = strings.ToLower(c.Indices[i].Name)

		icfg := c.Indices[i]
		if icfg.Type == "" {
			c.Indices[i].Type = TypeBasic
		}
		if !validTypes[c.Indices[i].Type] {
			return c, fmt.Errorf("invalid index type %q. Must be one of %v", c.Indices[i].Type, maps.Keys(validTypes))
		}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Set `related.threshold` to a value between 0 and 100 (Hugo's default is 80).
2. Lower the threshold toward 0 to get more (looser) matches, raise toward 100 for stricter matching.

Example fix

# before (hugo.toml)
[related]
threshold = 120
# after
[related]
threshold = 80

# threshold is a percentage
[related]
  threshold = 80  # must be 0–100

func validThreshold(t int) bool { return t >= 0 && t <= 100 }

if err := cfg.Validate(); err != nil {
    return fmt.Errorf("fix related.threshold (0-100): %w", err)
}

When it happens

Trigger: Site config with `related.threshold` set below 0 or above 100, e.g. `threshold = 120` or `threshold = -1`, caught in DecodeConfig at startup/config load.

Common situations: Treating threshold as an unbounded score or a fraction scaled wrong (e.g. entering 0.8 works, but 800 doesn't); copying values from other search tools that use different scales.

Related errors

• invalid index type %q. Must be one of %v
• cardinalityThreshold threshold must be between 0 and 100
• redirects must have either From or FromRe set
• failed to decode related config: %w
• failed to create config from result: %w

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