Tencent/WeKnora · error · AppError

opensearch: knn circuit breaker open

Error message

opensearch: knn circuit breaker open

What it means

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.

Source

Thrown at internal/application/repository/retriever/opensearch/errors.go:54

	// failed, or the k-NN plugin is missing on one or more cluster nodes.
	ErrConfigInvalid = errors.New("opensearch: invalid index config")

	// ErrFeatureNotEnabled — stubs.go returns this from methods whose real
	// implementation has not landed yet (CopyIndices / BatchUpdateChunk* /
	// swapToVersion, plus the read/write methods that a follow-up commit
	// will replace with production code).
	ErrFeatureNotEnabled = errors.New("opensearch: feature not enabled in this build")

	// ErrBatchTooLarge — Save / Delete batch exceeded the driver's sync
	// cap. Distinct from ErrFeatureNotEnabled so the service layer can
	// chunk + retry rather than treat the failure as "waiting on a future
	// implementation."
	ErrBatchTooLarge = errors.New("opensearch: batch size exceeds driver cap")

	// ErrCircuitBreaker — OpenSearch k-NN circuit breaker returned 429
	// (knn_circuit_breaker_exception). Classified as transient so the
	// caller can retry after the operator scales the cluster.
	ErrCircuitBreaker = errors.New("opensearch: knn circuit breaker open")
)

// isTransientErr classifies sentinel errors. Transient errors do not get
// persisted in ensureReady's initErr cache — they can be retried by the
// next caller after the underlying cause clears.
func isTransientErr(err error) bool {
	return errors.Is(err, ErrTransport) || errors.Is(err, ErrCircuitBreaker)
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Back off and retry the request after a delay; the breaker closes once knn memory pressure subsides
2. Raise the k-NN circuit breaker memory limit or reduce index memory usage (fewer/lower-dim vectors, force_merge, smaller shards)

When it happens

Trigger: Thrown at internal/application/repository/retriever/opensearch/errors.go:54 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/a5f4b74a8a99ea9a. Report an issue: GitHub.