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.

What it means

The conditional-transaction API (_begin_conditional_transaction plus _conditional_get/add/update/upsert/delete/commit) is implemented only over the HTTP transport. AsyncClient._require_http_conditional_transactions (async_client.py:61-66, mirrored in client.py:63) raises NotImplementedError when settings.chroma_server_http_port is None — i.e. when the client is embedded (PersistentClient/EphemeralClient) rather than HttpClient/AsyncHttpClient. Embedded mode talks to local SQLite directly and cannot provide the server-side transaction semantics these calls require.

Source

Thrown at chromadb/api/async_client.py:63

    A client internally stores its tenant and database and proxies calls to a
    Server API instance of Chroma. It treats the Server API and corresponding System
    as a singleton, so multiple clients connecting to the same resource will share the
    same API instance.

    Client implementations should be implement their own API-caching strategies.
    """

    # An internal admin client for verifying that databases and tenants exist
    _admin_client: AsyncAdminAPI

    tenant: str = DEFAULT_TENANT
    database: str = DEFAULT_DATABASE

    _server: AsyncServerAPI

    def _require_http_conditional_transactions(self) -> AsyncServerAPI:
        if self._system.settings.chroma_server_http_port is None:
            raise NotImplementedError(
                "Conditional transactions are only supported when connecting "
                "to a Chroma server via HttpClient."
            )
        return self._server

    @classmethod
    async def create(
        cls,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
        settings: Settings = Settings(),
    ) -> "AsyncClient":
        # Create an admin client for verifying that databases and tenants exist
        self = cls(settings=settings)
        SharedSystemClient._populate_data_from_system(self._system)

        self.tenant = tenant
        self.database = database

View on GitHub (pinned to aecdd12c8a)

Solutions

Run a Chroma server (chroma run, or docker run -p 8000:8000 chromadb/chroma) and connect with HttpClient/AsyncHttpClient
On embedded clients, use the plain add/get/upsert/delete APIs instead of conditional transactions
Feature-detect before use: conditional transactions are available only when the client is an HttpClient/AsyncHttpClient

Example fix

# before
client = chromadb.PersistentClient()
col = client.get_collection('c')
tx = await col._begin_conditional_transaction()  # NotImplementedError

# after
client = await chromadb.AsyncHttpClient('localhost', 8000)
col = await client.get_collection('c')
tx = await col._begin_conditional_transaction()

Defensive patterns

Strategy: validation

Validate before calling

import chromadb

def supports_conditional_transactions(client) -> bool:
    return isinstance(client, (chromadb.HttpClient, chromadb.AsyncHttpClient))

if not supports_conditional_transactions(client):
    raise RuntimeError(
        'conditional transactions need a Chroma server; '
        'connect with HttpClient/AsyncHttpClient or use plain add/get/upsert'
    )

Type guard

def is_http_client(client: object) -> bool:
    """True when the client talks to a chroma server over HTTP."""
    import chromadb
    return isinstance(client, (chromadb.HttpClient, chromadb.AsyncHttpClient))

Try / catch

try:
    tx = await collection._begin_conditional_transaction()
except NotImplementedError:
    # embedded (Persistent/Ephemeral) client: fall back to plain operations,
    # or require an HttpClient/AsyncHttpClient before running this code path
    raise

Prevention

Decide the transport up front: conditional-transaction features require a chroma server
Gate transactional code paths behind an is_http_client check
Run integration tests against the same transport (server) you use in production

When it happens

Trigger: client = chromadb.PersistentClient() (or EphemeralClient in tests), then any conditional-transaction call such as await collection._begin_conditional_transaction() or the _conditional_* methods → NotImplementedError.

Common situations: Transactional workflows developed against `chroma run` or Chroma Cloud, then executed locally with PersistentClient; test suites using ephemeral fixtures that exercise conditional add/update flows.

Related errors

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