{"record":{"id":"5a6fe26ca3d313de","repo":"weaviate/weaviate","slug":"find-best-entrypoint","errorCode":null,"errorMessage":"find best entrypoint","messagePattern":"find best entrypoint","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/vector/hnsw/insert.go","lineNumber":523,"sourceCode":"\t\t\th.compressor.Preload(nodeId, vector)\n\t\t} else {\n\t\t\th.cache.Preload(nodeId, vector)\n\t\t}\n\t}\n\n\th.insertMetrics.prepareAndInsertNode(before)\n\tbefore = time.Now()\n\n\tvar distancer compressionhelpers.CompressorDistancer\n\tvar returnFn compressionhelpers.ReturnDistancerFn\n\tif h.compressed.Load() {\n\t\tdistancer, returnFn = h.compressor.NewDistancer(vector)\n\t\tdefer returnFn()\n\t}\n\tentryPointID, err = h.findBestEntrypointForNode(ctx, currentMaximumLayer, targetLevel,\n\t\tentryPointID, vector, distancer)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"find best entrypoint\")\n\t}\n\n\th.insertMetrics.findEntrypoint(before)\n\tbefore = time.Now()\n\n\t// TODO: check findAndConnectNeighbors...\n\tif err := h.findAndConnectNeighbors(ctx, node, entryPointID, vector, distancer,\n\t\ttargetLevel, currentMaximumLayer, helpers.NewAllowList()); err != nil {\n\t\treturn errors.Wrap(err, \"find and connect neighbors\")\n\t}\n\n\th.insertMetrics.findAndConnectTotal(before)\n\tbefore = time.Now()\n\n\t// Clear maintenance flag before potential entrypoint promotion.\n\t// The defer above handles error paths; this explicit call ensures the node\n\t// is unmarked before it can become the global entrypoint.\n\tnode.unmarkAsMaintenance()","sourceCodeStart":505,"sourceCodeEnd":541,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/vector/hnsw/insert.go#L505-L541","documentation":"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.","triggerScenarios":"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).","commonSituations":"Request context cancellation/timeout during large imports; corrupted index state after crash without clean recovery; tombstone/cleanup jobs racing with inserts in older versions.","solutions":["Check the wrapped root cause; if it's context deadline exceeded, increase the insert timeout or reduce batch size.","If nodes/links are corrupted, rebuild the index (reindex the collection) to regenerate a consistent graph.","Ensure the process was not killed uncleanly; restore from a good backup if commit-log replay fails.","Retry the failed batch after the transient condition (e.g. shutdown) is resolved."],"exampleFix":"// before: no timeout on import context\nctx := context.Background()\nbucket.Add(ctx, vector)\n\n// after: generous deadline per insert\nctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)\ndefer cancel()\nif err := bucket.Add(ctx, vector); err != nil {\n\tif errors.Is(err, context.DeadlineExceeded) {\n\t\t// retry or reduce batch size\n\t}\n\treturn err\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"err := bucket.Add(ctx, vector)\nif err != nil && strings.Contains(err.Error(), \"find best entrypoint\") {\n\tif errors.Is(errors.Unwrap(errors.Unwrap(err)), context.DeadlineExceeded) {\n\t\treturn retryWithLongerTimeout(err)\n\t}\n\t// otherwise: possible graph corruption -> schedule reindex\n}","preventionTips":["Use generous timeouts for graph insert operations.","Shut down cleanly; avoid killing the process mid-write.","Schedule periodic consistency checks/reindexing after crash recovery."],"tags":["hnsw","vector-index","entrypoint","graph-traversal","go"],"backgroundTag":"hnsw-entrypoint-search-failed","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}