What causes "Auth credentials not specified" in chroma-core/chroma?

Pass the credential explicitly: auth: { provider: 'basic', credentials: 'admin:admin' }.

chroma-core/chroma · error · Error

Auth credentials not specified

Error message

Auth credentials not specified

What it means

authOptionsToAuthProvider throws this Error when the auth options given to new ChromaClient({ auth }) (or AdminClient) include a provider but leave credentials undefined. Note this check does NOT fall back to CHROMA_CLIENT_AUTH_CREDENTIALS itself - on the public client path you must set auth.credentials explicitly, even if the env var is set; the env-var fallback only happens inside the provider classes after this check passes.

Source

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

    const headerVal =
      headerType === "AUTHORIZATION" ? `Bearer ${creds}` : creds;
    this.credentials = {};
    this.credentials[headerKey] = headerVal;
  }

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

export const authOptionsToAuthProvider = (
  auth: AuthOptions,
): ClientAuthProvider => {
  if (auth.provider === undefined) {
    throw new Error("Auth provider not specified");
  }
  if (auth.credentials === undefined) {
    throw new Error("Auth credentials not specified");
  }
  switch (auth.provider) {
    case "basic":
      return new BasicAuthClientProvider(auth.credentials);
    case "token":
      return new TokenAuthClientProvider(
        auth.credentials,
        auth.tokenHeaderType,
      );
      break;
    default:
      throw new Error("Invalid auth provider");
  }
};

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the credential explicitly: auth: { provider: 'basic', credentials: 'admin:admin' }.
Or feed the env var through: auth: { provider: 'token', credentials: process.env.CHROMA_CLIENT_AUTH_CREDENTIALS } (making sure the var is actually set before construction).
If you only rely on the env var, omit the whole auth option so the provider fallback path applies, or guard at startup.

Example fix

// before
const client = new ChromaClient({ auth: { provider: 'token' } });

// after
const client = new ChromaClient({
  auth: {
    provider: 'token',
    credentials: process.env.CHROMA_CLIENT_AUTH_CREDENTIALS!,
  },
});

Defensive patterns

Strategy: validation

Validate before calling

const credentials = process.env.CHROMA_CLIENT_AUTH_CREDENTIALS;
if (!credentials) {
  throw new Error('Set CHROMA_CLIENT_AUTH_CREDENTIALS before creating an authenticated ChromaClient');
}
const client = new ChromaClient({ auth: { provider: 'basic', credentials } });

Try / catch

try {
  new ChromaClient({ auth });
} catch (e) {
  if (e instanceof Error && e.message === 'Auth credentials not specified') {
    // auth.credentials must be set explicitly even when the env var exists
  }
  throw e;
}

Prevention

Do not assume authOptionsToAuthProvider reads the env var - pass auth.credentials explicitly.
Validate credentials presence in your config loader and fail fast with a clear message.
Cover auth setup with a startup health check against the server.

When it happens

Trigger: new ChromaClient({ auth: { provider: 'basic' } }) with no credentials; auth: { provider: 'token', credentials: process.env.CHROMA_TOKEN } when CHROMA_TOKEN is unset (reads as undefined); spreading an options object whose credentials key is absent.

Common situations: Assuming the client reads CHROMA_CLIENT_AUTH_CREDENTIALS automatically when auth options are provided; env var present in one environment but not another; typo in the credentials key inside a config object.

Related errors

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