{"record":{"id":"a5f4b74a8a99ea9a","repo":"Tencent/WeKnora","slug":"opensearch-knn-circuit-breaker-open","errorCode":null,"errorMessage":"opensearch: knn circuit breaker open","messagePattern":"opensearch: knn circuit breaker open","errorType":"error_code","errorClass":"AppError","httpStatus":503,"severity":"error","filePath":"internal/application/repository/retriever/opensearch/errors.go","lineNumber":54,"sourceCode":"\t// failed, or the k-NN plugin is missing on one or more cluster nodes.\n\tErrConfigInvalid = errors.New(\"opensearch: invalid index config\")\n\n\t// ErrFeatureNotEnabled — stubs.go returns this from methods whose real\n\t// implementation has not landed yet (CopyIndices / BatchUpdateChunk* /\n\t// swapToVersion, plus the read/write methods that a follow-up commit\n\t// will replace with production code).\n\tErrFeatureNotEnabled = errors.New(\"opensearch: feature not enabled in this build\")\n\n\t// ErrBatchTooLarge — Save / Delete batch exceeded the driver's sync\n\t// cap. Distinct from ErrFeatureNotEnabled so the service layer can\n\t// chunk + retry rather than treat the failure as \"waiting on a future\n\t// implementation.\"\n\tErrBatchTooLarge = errors.New(\"opensearch: batch size exceeds driver cap\")\n\n\t// ErrCircuitBreaker — OpenSearch k-NN circuit breaker returned 429\n\t// (knn_circuit_breaker_exception). Classified as transient so the\n\t// caller can retry after the operator scales the cluster.\n\tErrCircuitBreaker = errors.New(\"opensearch: knn circuit breaker open\")\n)\n\n// isTransientErr classifies sentinel errors. Transient errors do not get\n// persisted in ensureReady's initErr cache — they can be retried by the\n// next caller after the underlying cause clears.\nfunc isTransientErr(err error) bool {\n\treturn errors.Is(err, ErrTransport) || errors.Is(err, ErrCircuitBreaker)\n}\n","sourceCodeStart":36,"sourceCodeEnd":63,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/repository/retriever/opensearch/errors.go#L36-L63","documentation":"Sentinel ErrCircuitBreaker: the OpenSearch k-NN circuit breaker tripped — the cluster returns knn_circuit_breaker_exception with HTTP 429 when the k-NN graph cache is under memory pressure, so vector queries/writes are shed to protect the node. Wrapped by the client so isTransientErr treats it as retryable.","triggerScenarios":"Thrown at internal/application/repository/retriever/opensearch/errors.go:54 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Back off and retry the request after a delay; the breaker closes once knn memory pressure subsides","Raise the k-NN circuit breaker memory limit or reduce index memory usage (fewer/lower-dim vectors, force_merge, smaller shards)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}