{"record":{"id":"eaa26afb5f5828b0","repo":"chroma-core/chroma","slug":"asyncclient-cannot-be-created-synchronously-use","errorCode":null,"errorMessage":"AsyncClient cannot be created synchronously. Use .from_system_async() instead.","messagePattern":"AsyncClient cannot be created synchronously\\. Use \\.from_system_async\\(\\) instead\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"chromadb/api/async_client.py","lineNumber":124,"sourceCode":"    @classmethod\n    # (we can't override and use from_system() because it's synchronous)\n    async def from_system_async(\n        cls,\n        system: System,\n        tenant: str = DEFAULT_TENANT,\n        database: str = DEFAULT_DATABASE,\n    ) -> \"AsyncClient\":\n        \"\"\"Create a client from an existing system. This is useful for testing and debugging.\"\"\"\n        return await AsyncClient.create(tenant, database, system.settings)\n\n    @classmethod\n    @override\n    def from_system(\n        cls,\n        system: System,\n    ) -> \"SharedSystemClient\":\n        \"\"\"AsyncClient cannot be created synchronously. Use .from_system_async() instead.\"\"\"\n        raise NotImplementedError(\n            \"AsyncClient cannot be created synchronously. Use .from_system_async() instead.\"\n        )\n\n    @override\n    async def get_user_identity(self) -> UserIdentity:\n        return await self._server.get_user_identity()\n\n    @override\n    async def set_tenant(self, tenant: str, database: str = DEFAULT_DATABASE) -> None:\n        await self._validate_tenant_database(tenant=tenant, database=database)\n        self.tenant = tenant\n        self.database = database\n\n    @override\n    async def set_database(self, database: str) -> None:\n        await self._validate_tenant_database(tenant=self.tenant, database=database)\n        self.database = database\n","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/async_client.py#L106-L142","documentation":"SharedSystemClient.from_system is a synchronous construction contract, but AsyncClient needs an awaited initialization, so its override raises NotImplementedError and directs you to the async classmethod from_system_async (chromadb/api/async_client.py:112-126). Any generic factory that calls cls.from_system(system) on whatever client class it was handed will trip this.","triggerScenarios":"AsyncClient.from_system(system); System-based factory or registry code that treats Client and AsyncClient uniformly; test fixtures copied from the sync client.","commonSituations":"Libraries wrapping both the sync and async clients behind one create function; incremental migration of sync code to asyncio.","solutions":["Use the async path: await AsyncClient.from_system_async(system)","Branch in shared factories: use from_system_async for AsyncClient, from_system for the sync Client","For normal usage prefer AsyncHttpClient(...) instead of manually building a System"],"exampleFix":"# before\nclient = AsyncClient.from_system(system)  # NotImplementedError\n\n# after\nclient = await AsyncClient.from_system_async(system)","handlingStrategy":"type-guard","validationCode":"from chromadb.api.async_client import AsyncClient\n\nasync def client_from_system(cls, system):\n    if isinstance(cls, type) and issubclass(cls, AsyncClient):\n        return await cls.from_system_async(system)\n    return cls.from_system(system)","typeGuard":"from chromadb.api.async_client import AsyncClient\n\ndef is_async_client_class(cls) -> bool:\n    \"\"\"True when cls must be constructed via from_system_async (awaited).\"\"\"\n    return isinstance(cls, type) and issubclass(cls, AsyncClient)","tryCatchPattern":"try:\n    client = SomeClient.from_system(system)\nexcept NotImplementedError as e:\n    if 'from_system_async' in str(e):\n        client = await AsyncClient.from_system_async(system)\n    else:\n        raise","preventionTips":["Always construct AsyncClient through its async classmethods (create, from_system_async)","In shared factories, branch on issubclass(cls, AsyncClient) before calling from_system","Prefer AsyncHttpClient(...) for everyday async usage — no manual System needed"],"tags":["python","asyncio","client-construction","not-implemented"],"backgroundTag":"sync-async-misuse","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}