{"record":{"id":"b265452590a0afb0","repo":"chroma-core/chroma","slug":"conditional-transactions-are-only-supported-when-c","errorCode":null,"errorMessage":"Conditional transactions are only supported when connecting to a Chroma server via HttpClient.","messagePattern":"Conditional transactions are only supported when connecting to a Chroma server via HttpClient\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"chromadb/api/async_client.py","lineNumber":63,"sourceCode":"    A client internally stores its tenant and database and proxies calls to a\n    Server API instance of Chroma. It treats the Server API and corresponding System\n    as a singleton, so multiple clients connecting to the same resource will share the\n    same API instance.\n\n    Client implementations should be implement their own API-caching strategies.\n    \"\"\"\n\n    # An internal admin client for verifying that databases and tenants exist\n    _admin_client: AsyncAdminAPI\n\n    tenant: str = DEFAULT_TENANT\n    database: str = DEFAULT_DATABASE\n\n    _server: AsyncServerAPI\n\n    def _require_http_conditional_transactions(self) -> AsyncServerAPI:\n        if self._system.settings.chroma_server_http_port is None:\n            raise NotImplementedError(\n                \"Conditional transactions are only supported when connecting \"\n                \"to a Chroma server via HttpClient.\"\n            )\n        return self._server\n\n    @classmethod\n    async def create(\n        cls,\n        tenant: str = DEFAULT_TENANT,\n        database: str = DEFAULT_DATABASE,\n        settings: Settings = Settings(),\n    ) -> \"AsyncClient\":\n        # Create an admin client for verifying that databases and tenants exist\n        self = cls(settings=settings)\n        SharedSystemClient._populate_data_from_system(self._system)\n\n        self.tenant = tenant\n        self.database = database","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/async_client.py#L45-L81","documentation":"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.","triggerScenarios":"client = chromadb.PersistentClient() (or EphemeralClient in tests), then any conditional-transaction call such as await collection._begin_conditional_transaction() or the _conditional_* methods → NotImplementedError.","commonSituations":"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.","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"],"exampleFix":"# before\nclient = chromadb.PersistentClient()\ncol = client.get_collection('c')\ntx = await col._begin_conditional_transaction()  # NotImplementedError\n\n# after\nclient = await chromadb.AsyncHttpClient('localhost', 8000)\ncol = await client.get_collection('c')\ntx = await col._begin_conditional_transaction()","handlingStrategy":"validation","validationCode":"import chromadb\n\ndef supports_conditional_transactions(client) -> bool:\n    return isinstance(client, (chromadb.HttpClient, chromadb.AsyncHttpClient))\n\nif not supports_conditional_transactions(client):\n    raise RuntimeError(\n        'conditional transactions need a Chroma server; '\n        'connect with HttpClient/AsyncHttpClient or use plain add/get/upsert'\n    )","typeGuard":"def is_http_client(client: object) -> bool:\n    \"\"\"True when the client talks to a chroma server over HTTP.\"\"\"\n    import chromadb\n    return isinstance(client, (chromadb.HttpClient, chromadb.AsyncHttpClient))","tryCatchPattern":"try:\n    tx = await collection._begin_conditional_transaction()\nexcept NotImplementedError:\n    # embedded (Persistent/Ephemeral) client: fall back to plain operations,\n    # or require an HttpClient/AsyncHttpClient before running this code path\n    raise","preventionTips":["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"],"tags":["python","client-mode","transactions","not-implemented","embedded-vs-server"],"backgroundTag":"feature-requires-http-client","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}