chroma-core/chroma · error · ChromaAuthError

Could not determine a database name from the current authent

Error message

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

What it means

Companion to the tenant check in Client.__init__: after resolving the user identity, maybe_set_tenant_and_database() also derives a database name from the auth method. If the identity provides none and no database= argument was given, construction fails with ChromaAuthError. It indicates the token/credentials carry no database information.

Source

Thrown at chromadb/api/client.py:103

            # 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:
            # If init fails after refcount was incremented, release references
            # to avoid a resource leak (the caller never receives the object to
            # call close() on it).
            if hasattr(self, "_admin_client"):

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the database explicitly: Client(tenant="acme", database="my_db").
Re-issue credentials/tokens that include the database claim.
Verify the auth provider settings and chroma_overwrite_singleton_tenant_database_access_from_auth configuration.

Example fix

# before
client = chromadb.HttpClient(settings=auth_settings, tenant="acme")  # no db 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_claims(token: str) -> dict:
    payload = token.split(".")[1]
    return json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))

claims = jwt_claims(os.environ["CHROMA_TOKEN"])
kwargs = {}
if "tenant" not in claims:
    kwargs["tenant"] = "acme"
if "database" not in claims:
    kwargs["database"] = "prod"
client = chromadb.HttpClient(settings=auth_settings, **kwargs)

Try / catch

from chromadb.errors import ChromaAuthError

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

Prevention

Pass database= explicitly whenever tokens don't guarantee it.
Encode tenant and database in every token your auth provider issues.
Centralize client construction in one helper that always sets both.

When it happens

Trigger: Token auth where the JWT includes a tenant claim but no database claim and Client() is created without database=; an auth provider returning an identity that names a tenant but not a database.

Common situations: Partially-configured RBAC tokens; auth provider upgrades that stopped embedding database info; apps that previously relied on the default database but enabled strict auth resolution.

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/84c4658065e0b0ae. Report an issue: GitHub.