chroma-core/chroma · error · RuntimeError

Component not running

Error message

Component not running

What it means

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.

Source

Thrown at chromadb/db/mixins/embeddings_queue.py:183

            t = Table("embeddings_queue")
            q = (
                self.querybuilder()
                .from_(t)
                .where(t.seq_id < ParameterValue(min_seq_id))
                .where(t.topic == ParameterValue(topic_name))
                .delete()
            )

            sql, params = get_sql(q, self.parameter_format())
            cur.execute(sql, params)

    @trace_method("SqlEmbeddingsQueue.submit_embedding", OpenTelemetryGranularity.ALL)
    @override
    def submit_embedding(
        self, collection_id: UUID, embedding: OperationRecord
    ) -> SeqId:
        if not self._running:
            raise RuntimeError("Component not running")

        return self.submit_embeddings(collection_id, [embedding])[0]

    @trace_method("SqlEmbeddingsQueue.submit_embeddings", OpenTelemetryGranularity.ALL)
    @override
    def submit_embeddings(
        self, collection_id: UUID, embeddings: Sequence[OperationRecord]
    ) -> Sequence[SeqId]:
        if not self._running:
            raise RuntimeError("Component not running")

        if len(embeddings) == 0:
            return []

        if len(embeddings) > self.max_batch_size:
            raise BatchSizeExceededError(
                f"""
                Cannot submit more than {self.max_batch_size:,} embeddings at once.

View on GitHub (pinned to aecdd12c8a)

Solutions

1. 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).
2. Drop stale component references after stop()/reset() and re-resolve them from a freshly started System.
3. In tests, use the provided fixtures/clients instead of hand-assembling the queue.

Example fix

# before
system = System(settings)
queue = system.instance(SqlEmbeddingsQueue)
queue.submit_embedding(collection_id, record)  # RuntimeError: Component not running

# after
system = System(settings)
system.start()
queue = system.instance(SqlEmbeddingsQueue)
queue.submit_embedding(collection_id, record)

def is_component_not_running(e: BaseException) -> bool:
    return isinstance(e, RuntimeError) and "Component not running" in str(e)

try:
    queue.submit_embedding(collection_id, record)
except RuntimeError as e:
    if "Component not running" in str(e):
        system.start()
        queue.submit_embedding(collection_id, record)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• BatchSizeExceededError
• Unknown error
• The requested resource could not be found
• Embedding function provided when already defined in the coll
• Aggregate input must be an Aggregate instance or object with

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/96171aa4a4edde9f. Report an issue: GitHub.