chroma-core/chroma · error · ChromaAuthError

Could not determine a tenant from the current authentication

Error message

Could not determine a tenant from the current authentication method. Please provide a tenant.

What it means

During synchronous Client construction with authentication enabled, Chroma fetches the user identity and calls maybe_set_tenant_and_database() to derive a tenant from the auth method (e.g. JWT claims). If the identity yields no tenant and the caller did not pass tenant=, init fails with ChromaAuthError. The code comment says this 'should not happen unless types are invalidated' — in practice it means the token/credentials carry no tenant information.

Source

Thrown at chromadb/api/client.py:99

                self.tenant = tenant
            if database is not None:
                self.database = database

            # Get the root system component we want to interact with
            self._server = self._system.instance(ServerAPI)

            user_identity = self.get_user_identity()

            maybe_tenant, maybe_database = maybe_set_tenant_and_database(
                user_identity,
                overwrite_singleton_tenant_database_access_from_auth=settings.chroma_overwrite_singleton_tenant_database_access_from_auth,
                user_provided_tenant=tenant,
                user_provided_database=database,
            )

            # this should not happen unless types are invalidated
            if maybe_tenant is None and tenant is None:
                raise ChromaAuthError(
                    "Could not determine a tenant from the current authentication method. Please provide a tenant."
                )
            if maybe_database is None and database is None:
                raise ChromaAuthError(
                    "Could not determine a database name from the current authentication method. Please provide a database name."
                )

            if maybe_tenant:
                self.tenant = maybe_tenant
            if maybe_database:
                self.database = maybe_database

            # Create an admin client for verifying that databases and tenants exist
            self._admin_client = AdminClient.from_system(self._system)
            self._validate_tenant_database(tenant=self.tenant, database=self.database)

            self._submit_client_start_event()
        except Exception:

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the tenant explicitly: Client(tenant="my_tenant", database="my_db").
Re-issue the token/credentials so they include the tenant claim the provider expects.
Check the auth configuration (CHROMA_SERVER_AUTHN_PROVIDER, credentials file contents, chroma_overwrite_singleton_tenant_database_access_from_auth) matches the deployment.

Example fix

# before
client = chromadb.HttpClient(settings=auth_settings)  # token lacks tenant claim -> ChromaAuthError

# after
client = chromadb.HttpClient(settings=auth_settings, tenant="acme", database="prod")

Defensive patterns

Strategy: validation

Validate before calling

import base64, json

def jwt_has_tenant(token: str) -> bool:
    try:
        payload = token.split(".")[1]
        claims = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
        return "tenant" in claims
    except Exception:
        return False

if not jwt_has_tenant(os.environ["CHROMA_TOKEN"]):
    tenant = "acme"  # pass explicitly: Client(tenant=tenant, ...)

Try / catch

from chromadb.errors import ChromaAuthError

try:
    client = chromadb.HttpClient(settings=auth_settings)
except ChromaAuthError as e:
    if "tenant" in str(e):
        client = chromadb.HttpClient(settings=auth_settings, tenant="acme")
    else:
        raise

Prevention

Always pass tenant= (and database=) explicitly when using token auth.
Verify issued tokens contain tenant claims before shipping them.
Smoke-test client construction in CI with the real auth settings.

When it happens

Trigger: Token auth (CHROMA_AUTH_TOKEN_TRANSPORT_HEADER etc.) where the JWT has no tenant claim and Client() is constructed without tenant=; an auth provider whose get_user_identity() returns an identity without tenant info; a credentials file that omits the tenant.

Common situations: Chroma RBAC/token deployments where the issued token is generic; rolling out authentication on an existing app that never passed tenant; switching auth providers without updating issued tokens.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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