chroma-core/chroma · error · Error

Credentials must be supplied via environment variable (CHROM

Error message

Credentials must be supplied via environment variable (CHROMA_CLIENT_AUTH_CREDENTIALS) or passed in as configuration.

What it means

BasicAuthClientProvider resolves credentials as constructorArg ?? process.env.CHROMA_CLIENT_AUTH_CREDENTIALS and throws this Error when both are absent. The credential string must be 'username:password'; it is base64-encoded into an Authorization: Basic header. Through the normal ChromaClient({ auth }) path, authOptionsToAuthProvider already rejects undefined credentials, so this exact message surfaces mainly when the provider class is instantiated directly (tests, custom integrations) with no argument while the env var is unset.

Source

Thrown at clients/js/packages/chromadb-core/src/auth.ts:44

export interface ClientAuthProvider {
  /**
   * Abstract method for authenticating a client.
   */
  authenticate(): AuthHeaders;
}

export class BasicAuthClientProvider implements ClientAuthProvider {
  private readonly credentials: AuthHeaders;

  /**
   * Creates a new BasicAuthClientProvider.
   * @param textCredentials - The credentials for the authentication provider. Must be of the form "username:password". If not supplied, the environment variable CHROMA_CLIENT_AUTH_CREDENTIALS will be used.
   * @throws {Error} If neither credentials provider or text credentials are supplied.
   */
  constructor(textCredentials: string | undefined) {
    const creds = textCredentials ?? process.env.CHROMA_CLIENT_AUTH_CREDENTIALS;
    if (creds === undefined) {
      throw new Error(
        "Credentials must be supplied via environment variable (CHROMA_CLIENT_AUTH_CREDENTIALS) or passed in as configuration.",
      );
    }
    this.credentials = {
      Authorization: "Basic " + base64Encode(creds),
    };
  }

  authenticate(): AuthHeaders {
    return this.credentials;
  }
}

export class TokenAuthClientProvider implements ClientAuthProvider {
  private readonly credentials: AuthHeaders;

  constructor(
    textCredentials: any,

View on GitHub (pinned to aecdd12c8a)

Solutions

Export the env var before constructing the client: export CHROMA_CLIENT_AUTH_CREDENTIALS='admin:admin'.
Or pass credentials explicitly: new ChromaClient({ auth: { provider: 'basic', credentials: 'admin:admin' } }).
Verify the value format is exactly 'username:password' (single colon) and that dotenv/config loading runs before client creation.

Example fix

// before
const auth = new BasicAuthClientProvider(undefined); // env var not set in CI

// after
import 'dotenv/config'; // ensure .env is loaded first
const auth = new BasicAuthClientProvider(process.env.CHROMA_CLIENT_AUTH_CREDENTIALS!);

Defensive patterns

Strategy: validation

Validate before calling

const creds =
  explicitCredentials ?? process.env.CHROMA_CLIENT_AUTH_CREDENTIALS;
if (creds === undefined) {
  throw new Error('Missing Chroma credentials: set CHROMA_CLIENT_AUTH_CREDENTIALS=user:password');
}
const provider = new BasicAuthClientProvider(creds);

Try / catch

try {
  new BasicAuthClientProvider(creds);
} catch (e) {
  if (e instanceof Error && e.message.includes('CHROMA_CLIENT_AUTH_CREDENTIALS')) {
    // fail startup with an actionable message; do not swallow and continue unauthenticated
  }
  throw e;
}

Prevention

Fail fast at boot: assert required env vars before building clients.
Use single-colon 'username:password' format and never include the 'Basic ' prefix yourself.
Add env-var presence checks to deployment checklists for Docker/CI stages.

When it happens

Trigger: new BasicAuthClientProvider(undefined) with CHROMA_CLIENT_AUTH_CREDENTIALS unset; constructing the provider with a variable that is undefined at runtime; CI/containers where the env var was never injected (through ChromaClient the equivalent failure is 'Auth credentials not specified').

Common situations: Deploying to Docker/K8s/CI without passing CHROMA_CLIENT_AUTH_CREDENTIALS; .env file not loaded before client construction (dotenv import order); local works (var in shell profile) but production 500s at startup.

Related errors

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