{"record":{"id":"96171aa4a4edde9f","repo":"chroma-core/chroma","slug":"component-not-running","errorCode":null,"errorMessage":"Component not running","messagePattern":"Component not running","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"chromadb/db/mixins/embeddings_queue.py","lineNumber":183,"sourceCode":"            t = Table(\"embeddings_queue\")\n            q = (\n                self.querybuilder()\n                .from_(t)\n                .where(t.seq_id < ParameterValue(min_seq_id))\n                .where(t.topic == ParameterValue(topic_name))\n                .delete()\n            )\n\n            sql, params = get_sql(q, self.parameter_format())\n            cur.execute(sql, params)\n\n    @trace_method(\"SqlEmbeddingsQueue.submit_embedding\", OpenTelemetryGranularity.ALL)\n    @override\n    def submit_embedding(\n        self, collection_id: UUID, embedding: OperationRecord\n    ) -> 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.","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/mixins/embeddings_queue.py#L165-L201","documentation":"submit_embedding is guarded by the component lifecycle flag: if the SqlEmbeddingsQueue's start() has not completed (or stop()/reset ran), _running is False and a builtin RuntimeError('Component not running') is thrown before any WAL write (chromadb/db/mixins/embeddings_queue.py:183). It is an internal-API invariant error, not part of the ChromaError hierarchy.","triggerScenarios":"Calling the internal SqlEmbeddingsQueue.submit_embedding(collection_id, record) before System.start() finished starting the queue component, or after System.stop()/reset() tore it down. Typical when tests build a System manually or embed the queue without the normal server lifecycle.","commonSituations":"Unit tests constructing a System and immediately using internals without system.start(); custom server harnesses that start only a subset of components; code paths that keep a handle to the queue across a reset and submit afterwards.","solutions":["Start the full system before use: create the System, register components, and call system.start() (or use a normal client like PersistentClient()/HttpClient() which manages the lifecycle).","Drop stale component references after stop()/reset() and re-resolve them from a freshly started System.","In tests, use the provided fixtures/clients instead of hand-assembling the queue."],"exampleFix":"# before\nsystem = System(settings)\nqueue = system.instance(SqlEmbeddingsQueue)\nqueue.submit_embedding(collection_id, record)  # RuntimeError: Component not running\n\n# after\nsystem = System(settings)\nsystem.start()\nqueue = system.instance(SqlEmbeddingsQueue)\nqueue.submit_embedding(collection_id, record)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def is_component_not_running(e: BaseException) -> bool:\n    return isinstance(e, RuntimeError) and \"Component not running\" in str(e)","tryCatchPattern":"try:\n    queue.submit_embedding(collection_id, record)\nexcept RuntimeError as e:\n    if \"Component not running\" in str(e):\n        system.start()\n        queue.submit_embedding(collection_id, record)\n    else:\n        raise","preventionTips":["Call system.start() and await readiness before any submit; prefer public clients.","Don't hold component references across stop()/reset() boundaries.","In tests, use provided fixtures/clients rather than hand-built Systems."],"tags":["chroma","internal-api","lifecycle","runtime-error","embeddings-queue"],"backgroundTag":"component-not-started","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}