What causes "failed to search for nearest centroid for posting %d" in weaviate/weaviate?

Inspect the wrapped cause; retry the merge if it was transient (context timeout, I/O hiccup).

failed to search for nearest centroid for posting %d

Error message

failed to search for nearest centroid for posting %d

What it means

To find merge candidates, doMerge searches the centroid index for the closest InternalPostingCandidates centroids to this posting's centroid. This error wraps a failure of that nearest-neighbor search over centroids. Without candidate centroids the merge cannot proceed and is aborted for this posting.

Source

Thrown at adapters/repos/db/vector/hfresh/merge.go:117

		vectorSet[v.ID()] = struct{}{}
	}

	// get posting centroid
	oldCentroid, err := h.Centroids.Get(postingID)
	if err != nil {
		return errors.Wrapf(err, "failed to get centroid for posting %d", postingID)
	}

	if oldCentroid == nil {
		h.logger.WithField("postingID", postingID).
			Debug("posting centroid not found, skipping merge operation")
		return nil
	}

	// search for the closest centroids
	nearest, err := h.Centroids.Search(oldCentroid.Uncompressed, h.config.InternalPostingCandidates, nil)
	if err != nil {
		return errors.Wrapf(err, "failed to search for nearest centroid for posting %d", postingID)
	}

	if nearest.Len() <= 1 {
		h.logger.WithField("postingID", postingID).
			Debug("no candidates found for merge operation, skipping")

		// persist the gc'ed posting
		err = h.PostingStore.Put(ctx, postingID, newPosting)
		if err != nil {
			return errors.Wrapf(err, "failed to put filtered posting %d", postingID)
		}
		// update the size of the posting after successful Persist
		err = h.setPostingVectorIDs(ctx, postingID, newPosting)
		if err != nil {
			return errors.Wrapf(err, "failed to set size of posting %d to %d", postingID, prevLen)
		}

		return nil

View on GitHub (pinned to 75aa4b6d11)

Solutions

Inspect the wrapped cause; retry the merge if it was transient (context timeout, I/O hiccup).
Validate shard integrity / run recovery if the centroid index fails searches repeatedly.
Check disk health and context timeout settings for background maintenance.
If reproducible after restart, rebuild the affected shard's index.

Defensive patterns

Strategy: retry

Validate before calling

if err := ctx.Err(); err != nil {
    return err
}

Try / catch

if err := merge.Execute(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to search for nearest centroid") {
        if errors.Is(err, context.DeadlineExceeded) {
            return retryWithBackoff(err)
        }
        // non-transient: inspect unwrapped cause for corruption
    }
    return err
}

Prevention

Size context deadlines for centroid searches over the full centroid set.
Validate InternalPostingCandidates config against index size.
Run post-crash integrity checks on the centroid index.
Rebuild the shard index if centroid searches persistently fail after restart.

When it happens

Trigger: h.Centroids.Search(oldCentroid.Uncompressed, h.config.InternalPostingCandidates, nil) errors — failure inside the centroid search structure (I/O, context cancellation, corrupt search state, malformed centroid vector).

Common situations: Corrupted or partially flushed centroid index after crash; context deadline exceeded on large centroid sets under load; misconfigured InternalPostingCandidates combined with storage failures; disk I/O problems on the shard.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/f6d52d1b470625b6. Report an issue: GitHub.