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

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.

Source

Thrown at chromadb/api/async_client.py:147

    async def get_user_identity(self) -> UserIdentity:
        return await self._server.get_user_identity()

    @override
    async def set_tenant(self, tenant: str, database: str = DEFAULT_DATABASE) -> None:
        await self._validate_tenant_database(tenant=tenant, database=database)
        self.tenant = tenant
        self.database = database

    @override
    async def set_database(self, database: str) -> None:
        await self._validate_tenant_database(tenant=self.tenant, database=database)
        self.database = database

    async def _validate_tenant_database(self, tenant: str, database: str) -> None:
        try:
            await self._admin_client.get_tenant(name=tenant)
        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:
            raise ValueError(
                f"Could not connect to tenant {tenant}. Are you sure it exists?"
            )

        try:
            await self._admin_client.get_database(name=database, tenant=tenant)
        except httpx.ConnectError:
            raise ValueError(
                "Could not connect to a Chroma server. Are you sure it is running?"
            )

    # region BaseAPI Methods

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

# before
client = await AsyncClient.create(host="localhost", port=8001)  # wrong port -> ValueError

# after
# confirm: curl http://localhost:8000/api/v2/heartbeat
client = await AsyncClient.create(host="localhost", port=8000)

Defensive patterns

Strategy: try-catch

Validate before calling

import httpx

async def chroma_reachable(host: str, port: int = 8000, timeout: float = 2.0) -> bool:
    try:
        r = await httpx.AsyncClient(timeout=timeout).get(
            f"http://{host}:{port}/api/v2/heartbeat"
        )
        return r.status_code == 200
    except httpx.ConnectError:
        return False

# await chroma_reachable("localhost", 8000) before AsyncClient.create(...)

Try / catch

import httpx

try:
    client = await AsyncClient.create(tenant="acme")
except ValueError as e:
    if isinstance(e.__cause__, httpx.ConnectError):
        # server unreachable -> fail fast with actionable message
        raise RuntimeError("Chroma server unreachable; start it or fix host/port") from e
    raise

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

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