chroma-core/chroma · error · ValueError

Could not connect to a Chroma server. Are you sure it is run

Error message

Could not connect to a Chroma server. Are you sure it is running?

What it means

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)).

Source

Thrown at chromadb/api/client.py:145

    @override
    def from_system(
        cls,
        system: System,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
    ) -> "Client":
        SharedSystemClient._populate_data_from_system(system)
        instance = cls(tenant=tenant, database=database, settings=system.settings)
        return instance

    # endregion

    @override
    def get_user_identity(self) -> UserIdentity:
        try:
            return self._server.get_user_identity()
        except httpx.ConnectError:
            raise ValueError(
                "Could not connect to a Chroma server. Are you sure it is running?"
            )
        # Propagate ChromaErrors
        except ChromaError as e:
            raise e
        except Exception as e:
            raise ValueError(str(e))

    # region BaseAPI Methods
    # Note - we could do this in less verbose ways, but they break type checking
    @override
    def heartbeat(self) -> int:
        """Return the server time in nanoseconds since epoch."""
        return self._server.heartbeat()

    @override
    def list_collections(
        self, limit: Optional[int] = None, offset: Optional[int] = None

View on GitHub (pinned to aecdd12c8a)

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).

Example fix

# before
client = chromadb.HttpClient(host="chroma", port=8000)  # server not up yet -> ValueError

# after
# wait for readiness, then construct
client = chromadb.HttpClient(host="chroma", port=8000)

Defensive patterns

Strategy: try-catch

Validate before calling

import httpx

def chroma_up(host: str, port: int = 8000) -> bool:
    try:
        return httpx.get(f"http://{host}:{port}/api/v2/heartbeat", timeout=2).status_code == 200
    except httpx.ConnectError:
        return False

if not chroma_up("localhost", 8000):
    raise SystemExit("start chroma before running this app")

Try / catch

try:
    client = chromadb.HttpClient(host=host, port=port)
except ValueError as e:
    if isinstance(e.__cause__, httpx.ConnectError):
        raise RuntimeError("Chroma unreachable — check server/host/port") from e
    raise

Prevention

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.

When it happens

Trigger: 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).

Common situations: App startup ordering — client module imported and client constructed before the Chroma container is healthy; wrong port in config; network policies blocking egress.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/0f62631366efd111. Report an issue: GitHub.