{"record":{"id":"6220598cd565c774","repo":"chroma-core/chroma","slug":"could-not-connect-to-a-chroma-server-are-you-sure","errorCode":null,"errorMessage":"Could not connect to a Chroma server. Are you sure it is running?","messagePattern":"Could not connect to a Chroma server\\. Are you sure it is running\\?","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/async_client.py","lineNumber":147,"sourceCode":"    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\n    async def _validate_tenant_database(self, tenant: str, database: str) -> None:\n        try:\n            await self._admin_client.get_tenant(name=tenant)\n        except httpx.ConnectError:\n            raise ValueError(\n                \"Could not connect to a Chroma server. Are you sure it is running?\"\n            )\n        # Propagate ChromaErrors\n        except ChromaError as e:\n            raise e\n        except Exception:\n            raise ValueError(\n                f\"Could not connect to tenant {tenant}. Are you sure it exists?\"\n            )\n\n        try:\n            await self._admin_client.get_database(name=database, tenant=tenant)\n        except httpx.ConnectError:\n            raise ValueError(\n                \"Could not connect to a Chroma server. Are you sure it is running?\"\n            )\n\n    # region BaseAPI Methods","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/async_client.py#L129-L165","documentation":"Raised while the async client validates that the configured tenant exists (during AsyncClient.create(), set_tenant(), or set_database()). The admin call get_tenant() failed with httpx.ConnectError, which means the TCP connection to the Chroma server could not be established at all. Chroma wraps the low-level httpx error in a plain ValueError with a friendlier message.","triggerScenarios":"await AsyncClient.create(host=..., port=...) when nothing is listening on the target address; CHROMA_SERVER_HOST/CHROMA_SERVER_PORT pointing at a stopped server; await client.set_tenant(...) or set_database(...) after the server went down; DNS name not resolving (httpx reports DNS failures as ConnectError).","commonSituations":"Running the client before `chroma run`; port mismatch (server started with --port 9000 but client defaults to 8000); Docker/Kubernetes network isolation (using localhost inside a container instead of host.docker.internal or a service DNS name); firewall or security group blocking the port; server crashed mid-session.","solutions":["Verify the server is reachable: curl http://<host>:8000/api/v2/heartbeat — it should return a nanosecond heartbeat value.","Start the server if it is not running: chroma run --host 0.0.0.0 --port 8000.","Check the host/port you pass to AsyncClient.create() (or the CHROMA_SERVER_HOST / CHROMA_SERVER_PORT env vars) against the server's actual bind address and port.","From inside a container, replace localhost with the correct service DNS name or host.docker.internal.","Check firewall/security-group rules on the port between client and server."],"exampleFix":"# before\nclient = await AsyncClient.create(host=\"localhost\", port=8001)  # wrong port -> ValueError\n\n# after\n# confirm: curl http://localhost:8000/api/v2/heartbeat\nclient = await AsyncClient.create(host=\"localhost\", port=8000)","handlingStrategy":"try-catch","validationCode":"import httpx\n\nasync def chroma_reachable(host: str, port: int = 8000, timeout: float = 2.0) -> bool:\n    try:\n        r = await httpx.AsyncClient(timeout=timeout).get(\n            f\"http://{host}:{port}/api/v2/heartbeat\"\n        )\n        return r.status_code == 200\n    except httpx.ConnectError:\n        return False\n\n# await chroma_reachable(\"localhost\", 8000) before AsyncClient.create(...)","typeGuard":null,"tryCatchPattern":"import httpx\n\ntry:\n    client = await AsyncClient.create(tenant=\"acme\")\nexcept ValueError as e:\n    if isinstance(e.__cause__, httpx.ConnectError):\n        # server unreachable -> fail fast with actionable message\n        raise RuntimeError(\"Chroma server unreachable; start it or fix host/port\") from e\n    raise","preventionTips":["Health-check the heartbeat endpoint before constructing the client.","Derive host/port from one config source so client and deployment can't drift.","In containers, never use localhost to reach a server in another container; use service DNS names."],"tags":["chroma","connection","async","http-client","client-init","tenant"],"backgroundTag":"connection-refused","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}