{"record":{"id":"fcf50ebe86d68de3","repo":"chroma-core/chroma","slug":"conditional-transactions-are-only-supported-when-c-fcf50e","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/client.py","lineNumber":65,"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    tenant: str = DEFAULT_TENANT\n    database: str = DEFAULT_DATABASE\n\n    _server: ServerAPI\n    # An internal admin client for verifying that databases and tenants exist\n    _admin_client: AdminAPI\n    _closed: bool = False\n\n    def _require_http_conditional_transactions(self) -> ServerAPI:\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    # region Initialization\n    def __init__(\n        self,\n        tenant: Optional[str] = DEFAULT_TENANT,\n        database: Optional[str] = DEFAULT_DATABASE,\n        settings: Settings = Settings(),\n    ) -> None:\n        super().__init__(settings=settings)\n        try:\n            if tenant is not None:\n                self.tenant = tenant\n            if database is not None:\n                self.database = database","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/client.py#L47-L83","documentation":"Conditional transactions (the collection.conditional API: conditional add/update/upsert/delete/get/commit with optimistic-concurrency semantics) are implemented only on the HTTP transport. Before dispatching, Client._require_http_conditional_transactions() checks settings.chroma_server_http_port; when it is None — i.e. you are on PersistentClient/EphemeralClient (embedded server, no HTTP port) — the call raises NotImplementedError.","triggerScenarios":"client = chromadb.PersistentClient(path='./db'); client.get_collection('c').conditional.add(...) — same for EphemeralClient; using Client(Settings(...)) without any chroma_server_http_port configured and then touching any .conditional* method.","commonSituations":"Prototyping with PersistentClient, then wiring in compare-and-swap writes; switching a HttpClient-based app to embedded mode for tests and having conditional transaction calls break.","solutions":["Switch to the HTTP client against a running server: client = chromadb.HttpClient(host=..., port=...).","Or replace the conditional-transaction logic with plain add/upsert (losing optimistic concurrency guarantees).","Keep embedded mode but implement your own locking/version check outside Chroma."],"exampleFix":"# before\nclient = chromadb.PersistentClient(path=\"./data\")\nclient.get_collection(\"docs\").conditional.add(...)  # NotImplementedError\n\n# after\nclient = chromadb.HttpClient(host=\"localhost\", port=8000)\nclient.get_collection(\"docs\").conditional.add(...)","handlingStrategy":"type-guard","validationCode":"def supports_conditional_txns(client) -> bool:\n    return client._system.settings.chroma_server_http_port is not None\n\nif not supports_conditional_txns(client):\n    raise RuntimeError(\"conditional transactions need chromadb.HttpClient\")","typeGuard":"import chromadb\n\ndef is_http_client(client) -> bool:\n    return isinstance(client, chromadb.api.client.Client) and (\n        client._system.settings.chroma_server_http_port is not None\n    )","tryCatchPattern":"try:\n    collection.conditional.add(...)\nexcept NotImplementedError:\n    raise RuntimeError(\n        \"switch to chromadb.HttpClient(host=..., port=...) to use conditional transactions\"\n    )","preventionTips":["Decide up front whether the app needs optimistic concurrency; if so, standardize on HttpClient everywhere, including tests.","Guard the code path with a capability check rather than relying on the exception."],"tags":["chroma","conditional-transactions","client-mode","not-implemented"],"backgroundTag":"unsupported-operation","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}