gohugoio/hugo · error

related threshold must be between 0 and 100

Error message

related threshold must be between 0 and 100

What it means

Returned by related.DecodeConfig in related/inverted_index.go:575 when the decoded Threshold is less than 0 or greater than 100. The related-content index uses threshold as a 0-100 relevance cutoff (normalized via the norm() helper above), so out-of-range values are rejected.

Solutions

1. Set threshold to an integer in [0,100]; typical values are 60-90.
2. If you intended a 0-1 scale, multiply by 100 (0.8 -> 80).
3. Re-run `hugo config` to confirm the resolved threshold is in range.

Example fix

// before
[related]
threshold = 0.8
// after
[related]
threshold = 80

// Clamp/validate threshold into [0,100].
if c.Threshold < 0 || c.Threshold > 100 {
    return errors.New("threshold out of range")
}

When it happens

Trigger: Setting `threshold` under [related] to a negative number or a value above 100 in hugo.toml, or passing such a value in a programmatic related config map.

Common situations: Misreading threshold as a 0-1 float (setting 0.8) or as a percentile above 100, or a copy-paste from a different config schema.

Related errors

• empty related config provided
• failed to decode related config
• invalid index type . Must be one of
• no related config provided
• config needs a filename

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

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