{"record":{"id":"0f62631366efd111","repo":"chroma-core/chroma","slug":"could-not-connect-to-a-chroma-server-are-you-sure-0f6263","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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/client.py","lineNumber":145,"sourceCode":"    @override\n    def from_system(\n        cls,\n        system: System,\n        tenant: str = DEFAULT_TENANT,\n        database: str = DEFAULT_DATABASE,\n    ) -> \"Client\":\n        SharedSystemClient._populate_data_from_system(system)\n        instance = cls(tenant=tenant, database=database, settings=system.settings)\n        return instance\n\n    # endregion\n\n    @override\n    def get_user_identity(self) -> UserIdentity:\n        try:\n            return self._server.get_user_identity()\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 as e:\n            raise ValueError(str(e))\n\n    # region BaseAPI Methods\n    # Note - we could do this in less verbose ways, but they break type checking\n    @override\n    def heartbeat(self) -> int:\n        \"\"\"Return the server time in nanoseconds since epoch.\"\"\"\n        return self._server.heartbeat()\n\n    @override\n    def list_collections(\n        self, limit: Optional[int] = None, offset: Optional[int] = None","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/client.py#L127-L163","documentation":"Client.get_user_identity() is the first server call made inside synchronous Client.__init__ (HttpClient), so it is usually the first place a dead server is noticed. When it fails with httpx.ConnectError, Chroma re-raises it as a plain ValueError with the 'Are you sure it is running?' message; any other non-Chroma exception from that call is re-raised as ValueError(str(e)).","triggerScenarios":"chromadb.HttpClient(host, port) or Client(settings with chroma_server_http_port) constructed while the server is down or unreachable; wrong host/port; DNS failure (httpx surfaces it as ConnectError).","commonSituations":"App startup ordering — client module imported and client constructed before the Chroma container is healthy; wrong port in config; network policies blocking egress.","solutions":["Verify reachability first: curl http://<host>:8000/api/v2/heartbeat.","Start the server or fix its address/port in the client construction or env vars.","Defer client creation until the server health check passes (startup hook / readiness probe)."],"exampleFix":"# before\nclient = chromadb.HttpClient(host=\"chroma\", port=8000)  # server not up yet -> ValueError\n\n# after\n# wait for readiness, then construct\nclient = chromadb.HttpClient(host=\"chroma\", port=8000)","handlingStrategy":"try-catch","validationCode":"import httpx\n\ndef chroma_up(host: str, port: int = 8000) -> bool:\n    try:\n        return httpx.get(f\"http://{host}:{port}/api/v2/heartbeat\", timeout=2).status_code == 200\n    except httpx.ConnectError:\n        return False\n\nif not chroma_up(\"localhost\", 8000):\n    raise SystemExit(\"start chroma before running this app\")","typeGuard":null,"tryCatchPattern":"try:\n    client = chromadb.HttpClient(host=host, port=port)\nexcept ValueError as e:\n    if isinstance(e.__cause__, httpx.ConnectError):\n        raise RuntimeError(\"Chroma unreachable — check server/host/port\") from e\n    raise","preventionTips":["Gate client creation on a readiness/health check of the server.","Construct the client lazily on first use, not at module import time.","Fail deployment startup when the dependency is down instead of retrying forever."],"tags":["chroma","connection","http-client","client-init","sync"],"backgroundTag":"connection-refused","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}