{"record":{"id":"90a2cd88be4e5fcd","repo":"Tencent/WeKnora","slug":"opensearch-batch-size-exceeds-driver-cap","errorCode":null,"errorMessage":"opensearch: batch size exceeds driver cap","messagePattern":"opensearch: batch size exceeds driver cap","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/repository/retriever/opensearch/errors.go","lineNumber":49,"sourceCode":"\t// ErrVersionUnsupported — cluster is not OpenSearch, is OS 1.x, or is\n\t// OS 2.0~2.3 (pre-Lucene-HNSW-GA). probeVersion enforces.\n\tErrVersionUnsupported = errors.New(\"opensearch: cluster version unsupported\")\n\n\t// ErrConfigInvalid — IndexConfig / storeID / sanitizeIndexName guard\n\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":31,"sourceCodeEnd":63,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/repository/retriever/opensearch/errors.go#L31-L63","documentation":"Sentinel ErrBatchTooLarge: Save/Delete rejected before contacting OpenSearch because the bulk request exceeded a driver-side sync limit — either estimated body over 10MB (given vector dims) or more than 1000 documents in one batch. It guards cluster memory and load, not a server failure.","triggerScenarios":"Thrown at internal/application/repository/retriever/opensearch/errors.go:49 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Split the batch into chunks of at most 1000 documents (and below the 10MB estimated body cap) and retry each chunk","Reduce vector dimensions or payload size per document, or stream items in smaller groups instead of one bulk call"],"exampleFix":null,"handlingStrategy":"validation","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"}