weaviate/weaviate · error

find best entrypoint

Error message

find best entrypoint

What it means

addOne must locate the best entrypoint node from which to descend the HNSW layers for the new node. This error wraps a failure of findBestEntrypointForNode — i.e. graph traversal/search during entrypoint selection failed, usually due to corrupted node links, a context cancellation, or internal search errors.

Source

Thrown at adapters/repos/db/vector/hnsw/insert.go:523

			h.compressor.Preload(nodeId, vector)
		} else {
			h.cache.Preload(nodeId, vector)
		}
	}

	h.insertMetrics.prepareAndInsertNode(before)
	before = time.Now()

	var distancer compressionhelpers.CompressorDistancer
	var returnFn compressionhelpers.ReturnDistancerFn
	if h.compressed.Load() {
		distancer, returnFn = h.compressor.NewDistancer(vector)
		defer returnFn()
	}
	entryPointID, err = h.findBestEntrypointForNode(ctx, currentMaximumLayer, targetLevel,
		entryPointID, vector, distancer)
	if err != nil {
		return errors.Wrap(err, "find best entrypoint")
	}

	h.insertMetrics.findEntrypoint(before)
	before = time.Now()

	// TODO: check findAndConnectNeighbors...
	if err := h.findAndConnectNeighbors(ctx, node, entryPointID, vector, distancer,
		targetLevel, currentMaximumLayer, helpers.NewAllowList()); err != nil {
		return errors.Wrap(err, "find and connect neighbors")
	}

	h.insertMetrics.findAndConnectTotal(before)
	before = time.Now()

	// Clear maintenance flag before potential entrypoint promotion.
	// The defer above handles error paths; this explicit call ensures the node
	// is unmarked before it can become the global entrypoint.
	node.unmarkAsMaintenance()

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check the wrapped root cause; if it's context deadline exceeded, increase the insert timeout or reduce batch size.
2. If nodes/links are corrupted, rebuild the index (reindex the collection) to regenerate a consistent graph.
3. Ensure the process was not killed uncleanly; restore from a good backup if commit-log replay fails.
4. Retry the failed batch after the transient condition (e.g. shutdown) is resolved.

Example fix

// before: no timeout on import context
ctx := context.Background()
bucket.Add(ctx, vector)

// after: generous deadline per insert
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()
if err := bucket.Add(ctx, vector); err != nil {
	if errors.Is(err, context.DeadlineExceeded) {
		// retry or reduce batch size
	}
	return err
}

err := bucket.Add(ctx, vector)
if err != nil && strings.Contains(err.Error(), "find best entrypoint") {
	if errors.Is(errors.Unwrap(errors.Unwrap(err)), context.DeadlineExceeded) {
		return retryWithLongerTimeout(err)
	}
	// otherwise: possible graph corruption -> schedule reindex
}

When it happens

Trigger: Inserting a vector (AddBatch/AddMultiBatch) when findBestEntrypointForNode returns an error: context canceled/deadline exceeded during search, or reading a node with dangling/broken neighbor links (e.g. after an unclean shutdown or torn commit log).

Common situations: Request context cancellation/timeout during large imports; corrupted index state after crash without clean recovery; tombstone/cleanup jobs racing with inserts in older versions.

Related errors

• find and connect neighbors
• pick entrypoint at level beginning
• index is not hnsw
• drop vector index %q: %w
• delete from vector index of vector %q: %w

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