{"record":{"id":"84fd68ac45dd66f6","repo":"chroma-core/chroma","slug":"batchsizeexceedederror","errorCode":"BatchSizeExceededError","errorMessage":"Cannot submit more than {max_batch_size:,} embeddings at once.\nPlease submit your embeddings in batches of size\n{max_batch_size:,} or less.","messagePattern":"Cannot submit more than (.+?) embeddings at once\\.\nPlease submit your embeddings in batches of size\n(.+?) or less\\.","errorType":"exception","errorClass":"BatchSizeExceededError","httpStatus":413,"severity":"error","filePath":"chromadb/db/mixins/embeddings_queue.py","lineNumber":199,"sourceCode":"    ) -> SeqId:\n        if not self._running:\n            raise RuntimeError(\"Component not running\")\n\n        return self.submit_embeddings(collection_id, [embedding])[0]\n\n    @trace_method(\"SqlEmbeddingsQueue.submit_embeddings\", OpenTelemetryGranularity.ALL)\n    @override\n    def submit_embeddings(\n        self, collection_id: UUID, embeddings: Sequence[OperationRecord]\n    ) -> Sequence[SeqId]:\n        if not self._running:\n            raise RuntimeError(\"Component not running\")\n\n        if len(embeddings) == 0:\n            return []\n\n        if len(embeddings) > self.max_batch_size:\n            raise BatchSizeExceededError(\n                f\"\"\"\n                Cannot submit more than {self.max_batch_size:,} embeddings at once.\n                Please submit your embeddings in batches of size\n                {self.max_batch_size:,} or less.\n                \"\"\"\n            )\n\n        # This creates the persisted configuration if it doesn't exist.\n        # It should be run as soon as possible (before any WAL mutations) since the default configuration depends on the WAL size.\n        # (We can't run this in __init__()/start() because the migrations have not been run at that point and the table may not be available.)\n        _ = self.config\n\n        topic_name = create_topic_name(\n            self._tenant, self._topic_namespace, collection_id\n        )\n\n        t = Table(\"embeddings_queue\")\n        insert = (","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/mixins/embeddings_queue.py#L181-L217","documentation":"submit_embeddings enforces a hard cap: if len(embeddings) exceeds max_batch_size, chromadb.errors.BatchSizeExceededError is raised and nothing is written (chromadb/db/mixins/embeddings_queue.py:199). The cap is derived from SQLite's compiled MAX_VARIABLE_NUMBER pragma limit divided by VARIABLES_PER_RECORD (fallback 999 // VARIABLES_PER_RECORD), because each record binds many SQL parameters in one statement.","triggerScenarios":"Submitting more than max_batch_size OperationRecords to the internal SqlEmbeddingsQueue in one call — e.g. a bulk ingestion path that bypasses the client's own batching, or a client max batch size setting raised above what the queue's SQLite limit allows.","commonSituations":"Bulk-loading large datasets through internal APIs without chunking; custom clients that pass big add() batches straight through; changing the embedding-function or record shape so variables-per-record grows and shrinks the effective cap; older SQLite builds where MAX_VARIABLE_NUMBER is 999 making the cap very small.","solutions":["Chunk submissions to at most queue.max_batch_size records per call (read the property; do not hardcode).","If you control the deployment, use a SQLite build with a higher MAX_VARIABLE_NUMBER (modern builds default to 32766/250000), which raises the cap automatically.","Keep public client max_batch_size settings aligned with (not above) the queue's derived limit."],"exampleFix":"# before\nseq_ids = queue.submit_embeddings(collection_id, records)  # BatchSizeExceededError if too large\n\n# after\nstep = queue.max_batch_size\nseq_ids: list = []\nfor i in range(0, len(records), step):\n    seq_ids.extend(queue.submit_embeddings(collection_id, records[i:i + step]))","handlingStrategy":"validation","validationCode":"batch = min(len(records), queue.max_batch_size)\nseq_ids = []\nfor i in range(0, len(records), queue.max_batch_size):\n    seq_ids.extend(queue.submit_embeddings(collection_id, records[i:i + queue.max_batch_size]))","typeGuard":"def is_batch_too_large(e: BaseException) -> bool:\n    import chromadb.errors\n    return isinstance(e, chromadb.errors.BatchSizeExceededError)","tryCatchPattern":"from chromadb.errors import BatchSizeExceededError\ntry:\n    queue.submit_embeddings(collection_id, records)\nexcept BatchSizeExceededError:\n    step = queue.max_batch_size\n    for i in range(0, len(records), step):\n        queue.submit_embeddings(collection_id, records[i:i + step])","preventionTips":["Never hardcode a batch size; read queue.max_batch_size (derived from SQLite's MAX_VARIABLE_NUMBER).","Chunk at the call site before submitting, especially for bulk loads.","If self-hosting, prefer a modern SQLite with a high MAX_VARIABLE_NUMBER to raise the cap."],"tags":["chroma","internal-api","embeddings-queue","batching","sqlite-limits"],"backgroundTag":"batch-size-limit-exceeded","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}