chroma-core/chroma · error · ValueError

Could not connect to tenant {tenant}. Are you sure it exists

Error message

Could not connect to tenant {tenant}. Are you sure it exists?

What it means

Catch-all branch in the async client's tenant validation: get_tenant() raised something that is neither httpx.ConnectError nor a ChromaError. Note that a genuinely missing tenant does NOT produce this error — the server returns a structured 404 that the HTTP client maps to a ChromaError, which is re-raised verbatim by the `except ChromaError` branch above. So this misleading "Are you sure it exists?" ValueError almost always masks a different, unexpected failure (a proxy response that is not a Chroma error envelope, a protocol error, a buggy auth provider).

Source

Thrown at chromadb/api/async_client.py:154

        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
    # Note - we could do this in less verbose ways, but they break type checking
    @override
    async def heartbeat(self) -> int:
        return await self._server.heartbeat()

    @override
    async def list_collections(

View on GitHub (pinned to aecdd12c8a)

Solutions

Inspect the chained cause — catch ValueError and print e.__cause__ (or the full traceback) to see the real underlying exception and response body.
Test the server directly, bypassing any proxy: curl http://<host>:8000/api/v2/v2/tenant/<name> style admin endpoints or at least /api/v2/heartbeat.
Align client and server chromadb versions so error envelopes match.
If a proxy is in the path, check its logs and make sure it forwards Chroma's JSON error bodies unchanged.
Only then verify the tenant actually exists via an admin API call.

Example fix

# before
try:
    client = await AsyncClient.create(tenant="acme")
except ValueError as e:
    print(e)  # 'Could not connect to tenant acme...' -- misleading

# after
except ValueError as e:
    print("real cause:", repr(e.__cause__))  # e.g. Exception('502 Bad Gateway') from proxy

Defensive patterns

Strategy: try-catch

Try / catch

from chromadb.errors import ChromaError

try:
    client = await AsyncClient.create(tenant="acme")
except ValueError as e:
    cause = e.__cause__
    if isinstance(cause, ChromaError):
        raise cause  # real Chroma error (e.g. tenant truly missing)
    # otherwise an unexpected/proxy error hides behind the message
    raise RuntimeError(f"tenant validation failed unexpectedly: {cause!r}") from e

Prevention

Always log e.__cause__ when this ValueError appears — the message itself is misleading.
Test tenants through the admin API directly when proxies are in the path.
Keep client and server chromadb versions aligned so error envelopes parse.

When it happens

Trigger: A reverse proxy/LB in front of Chroma returns a non-Chroma error (502/504 HTML or plain-text body), which _raise_chroma_error converts to a bare Exception; a very old Chroma server that does not return structured error JSON; a custom auth provider or transport raising a non-Chroma exception; httpx.RemoteProtocolError from a truncated response.

Common situations: nginx/traefik returning 502 while the Chroma container restarts; API-gateway rate limiting with a non-Chroma response body; mixed client/server versions where the error envelope differs; debugging in the wrong direction because the message mentions tenants.

Related errors

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