chroma-core/chroma · error · NotImplementedError

Conditional transactions are not supported by SegmentAPI

Error message

Conditional transactions are not supported by SegmentAPI

What it means

Conditional (compare-and-set style) collection transactions — entered via collection.transaction(), which calls _begin_conditional_transaction — are not supported by the embedded SegmentAPI backend. Every entry point (_begin_conditional_transaction, _conditional_get, and siblings) funnels through _unsupported_conditional_transactions, which raises NotImplementedError; the machinery lives on a Chroma server.

Source

Thrown at chromadb/api/segment.py:834

        records_to_submit = list(
            _records(operation=t.Operation.DELETE, ids=ids_to_delete)
        )
        self._validate_embedding_record_set(scan.collection, records_to_submit)
        self._producer.submit_embeddings(collection_id, records_to_submit)

        deleted_count = len(ids_to_delete)

        self._product_telemetry_client.capture(
            CollectionDeleteEvent(
                collection_uuid=str(collection_id), delete_amount=deleted_count
            )
        )

        return DeleteResult(deleted=deleted_count)

    def _unsupported_conditional_transactions(self) -> NoReturn:
        raise NotImplementedError(
            "Conditional transactions are not supported by SegmentAPI"
        )

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

    @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,

View on GitHub (pinned to aecdd12c8a)

Solutions

Use chromadb.HttpClient against a Chroma server for transactional workflows
When embedded, replace the transaction with a plain get -> modify -> add/upsert and accept the race
Feature-detect: wrap collection.transaction() in try/except NotImplementedError and branch

Example fix

// before
with coll.transaction() as tx:  # NotImplementedError embedded
    rec = tx.get(ids=[rid])

// after
try:
    with coll.transaction() as tx:
        rec = tx.get(ids=[rid])
except NotImplementedError:
    rec = coll.get(ids=[rid])  # non-transactional fallback

Defensive patterns

Strategy: try-catch

Validate before calling

import chromadb

def supports_transactions(client: chromadb.ClientAPI) -> bool:
    impl = client.get_settings().chroma_api_impl
    return impl not in ('chromadb.api.segment.SegmentAPI', 'chromadb.api.rust.RustBindingsAPI')

Try / catch

try:
    with coll.transaction() as tx:
        rec = tx.get(ids=[rid])
        # ... modify and write via tx
except NotImplementedError:
    # embedded fallback: non-transactional read-modify-write
    rec = coll.get(ids=[rid])

Prevention

Reserve collection.transaction() for server-backed deployments
Isolate transactional code paths behind an interface so an embedded fallback is pluggable
Mark embedded test suites as skipping transaction tests

When it happens

Trigger: Calling collection.transaction() (opening a ConditionalCollectionTransaction) or any _begin_conditional_transaction/_conditional_get/_conditional_* method on an embedded client (chromadb.Client, EphemeralClient, PersistentClient).

Common situations: Transactional read-modify-write code written against a Chroma server is reused in embedded CI runs or notebooks; examples copied from server documentation run against PersistentClient.

Related errors

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