gohugoio/hugo · error

index not found

Error message

index %q not found

What it means

Returned by InvertedIndex.Search when one of the index names in opts.Indices does not match any IndexConfig.Name in the configured indices. The search validates each requested index name against the config before building the query, so a typo or a removed index name fails fast here.

Solutions

1. Check the [related.indices] config in hugo.toml and confirm the index Name matches what is passed to Search.
2. Update any templates/partials that call .Related / Related indexing to use the current index name.
3. Remember index names are lowercased during DecodeConfig -- supply lowercase names.

Example fix

// before: config defines "keywords" but search asks for "tags"
related, _ := idx.Search(ctx, related.SearchOpts{Indices: []string{"tags"}})

// after
related, _ := idx.Search(ctx, related.SearchOpts{Indices: []string{"keywords"}})

// Verify index names exist before searching.
func validIndexNames(cfg related.Config, names []string) error {
    known := map[string]bool{}
    for _, i := range cfg.Indices { known[strings.ToLower(i.Name)] = true }
    for _, n := range names {
        if !known[strings.ToLower(n)] {
            return fmt.Errorf("unknown related index %q", n)
        }
    }
    return nil
}

docs, err := idx.Search(ctx, related.SearchOpts{Indices: names})
if err != nil && strings.Contains(err.Error(), "not found") {
    // index name mismatch -- fix config or input
}

When it happens

Trigger: Calling Search with SearchOpts{Indices: []string{"tags"}} when the related config only defines indices named "keywords" and "date". Also triggered when related search templates reference an index that was renamed or removed in a config refactor.

Common situations: Renaming an index in the [related] config without updating related.html partial that references the old name; configuring a custom index but misspelling it in a template; upgrading Hugo where default index names changed.

Related errors

• failed to decode related config
• empty related config provided
• index config for not found
• index for not found
• index not valid

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

Appendix: source

Thrown at related/inverted_index.go:359

// against query options in opts.
// The resulting document set will be sorted according to number of matches
// and the index weights, and any matches with a rank below the configured
// threshold (normalize to 0..100) will be removed.
// If an index name is provided, only that index will be queried.
func (idx *InvertedIndex) Search(ctx context.Context, opts SearchOpts) ([]Document, error) {
	var (
		queryElements []queryElement
		configs       IndicesConfig
	)

	if len(opts.Indices) == 0 {
		configs = idx.cfg.Indices
	} else {
		configs = make(IndicesConfig, len(opts.Indices))
		for i, indexName := range opts.Indices {
			cfg, found := idx.getIndexCfg(indexName)
			if !found {
				return nil, fmt.Errorf("index %q not found", indexName)
			}
			configs[i] = cfg
		}
	}

	for _, cfg := range configs {
		var keywords []Keyword
		if opts.Document != nil {
			k, err := opts.Document.RelatedKeywords(cfg)
			if err != nil {
				return nil, err
			}
			keywords = append(keywords, k...)
		}
		if cfg.Type == TypeFragments {
			for _, fragment := range opts.Fragments {
				keywords = append(keywords, FragmentKeyword(fragment))
			}

View on GitHub (pinned to 52c9bd7908)