chroma-core/chroma · error · NotImplementedError

Conditional transactions are only supported when connecting

Error message

Conditional transactions are only supported when connecting to a Chroma server via HttpClient. The Rust bindings (embedded mode) do not support conditional transaction operations.

What it means

RustBindingsAPI._begin_conditional_transaction (chromadb/api/rust.py:646) delegates to _unsupported_conditional_transactions(), which raises NotImplementedError with this message. Conditional (optimistic, snapshot-isolated) transactions are a Chroma-server feature; acquiring a ConditionalCollectionTransaction in embedded Rust mode fails immediately because the Rust bindings implement none of the _conditional_* operations.

Source

Thrown at chromadb/api/rust.py:646

            tenant,
            database,
        )

        self.product_telemetry_client.capture(
            CollectionDeleteEvent(
                collection_uuid=str(collection_id),
                delete_amount=deleted,
            )
        )

        return DeleteResult(deleted=deleted)

    @override
    def _begin_conditional_transaction(self) -> object:
        self._unsupported_conditional_transactions()

    def _unsupported_conditional_transactions(self) -> NoReturn:
        raise NotImplementedError(
            "Conditional transactions are only supported when connecting "
            "to a Chroma server via HttpClient. The Rust bindings "
            "(embedded mode) do not support conditional transaction operations."
        )

    @override
    def _conditional_get(
        self,
        transaction: object,
        collection_id: UUID,
        ids: Optional[IDs] = None,
        where: Optional[Where] = None,
        limit: Optional[int] = None,
        offset: Optional[int] = None,
        where_document: Optional[WhereDocument] = None,
        include: Include = IncludeMetadataDocuments,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,

View on GitHub (pinned to aecdd12c8a)

Solutions

Use chromadb.HttpClient against a Chroma server for conditional transactions
In embedded mode, use plain collection operations (get/query then upsert) - a single embedded process has no cross-client races, so optimistic transactions are unnecessary
Add a lock or serialize access in your own code when you need read-modify-write atomicity embedded

Example fix

# before (raises NotImplementedError on Rust bindings)
txn = collection.transaction
txn.run(lambda t: t.add(ids=['a'], embeddings=[[0.1]]))

# after - server client for transactional semantics
client = chromadb.HttpClient(host='localhost', port=8000)
txn = client.get_collection('docs').transaction
txn.run(lambda t: t.add(ids=['a'], embeddings=[[0.1]]))

Defensive patterns

Strategy: fallback

Validate before calling

def supports_conditional_transactions(client) -> bool:
    """Conditional transactions exist only on HttpClient."""
    return type(client._server).__module__.startswith('chromadb.api.fastapi')

Try / catch

try:
    txn = collection.transaction
except NotImplementedError:
    # embedded: no optimistic transactions; serialize access yourself
    txn = None
if txn is None:
    existing = collection.get(ids=['a'])
    collection.upsert(ids=['a'], embeddings=[[0.1]])
else:
    txn.run(lambda t: t.upsert(ids=['a'], embeddings=[[0.1]]))

Prevention

Acquire collection.transaction only when connected to a Chroma server
In single-process embedded mode, guard read-modify-write cycles with a local lock instead of transactions
Factor transactional code into a strategy that has server and embedded implementations

When it happens

Trigger: With a Rust bindings client (chromadb.RustClient or chroma_api_impl='chromadb.api.rust.RustBindingsAPI'), merely accessing collection.transaction - the ConditionalCollectionTransaction constructor calls _begin_conditional_transaction (chromadb/api/models/ConditionalCollectionTransaction.py:57) - or calling any txn.get/add/upsert/delete/run on it.

Common situations: Writing concurrency-safe read-modify-write code against a Chroma server and then running unit tests with an embedded Rust client; library code shared between server and embedded deployments that assumes transactions exist everywhere.

Related errors

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