{"record":{"id":"95968566980feea7","repo":"chroma-core/chroma","slug":"credentials-must-be-supplied-via-environment-varia","errorCode":null,"errorMessage":"Credentials must be supplied via environment variable (CHROMA_CLIENT_AUTH_CREDENTIALS) or passed in as configuration.","messagePattern":"Credentials must be supplied via environment variable \\(CHROMA_CLIENT_AUTH_CREDENTIALS\\) or passed in as configuration\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/auth.ts","lineNumber":44,"sourceCode":"export interface ClientAuthProvider {\n  /**\n   * Abstract method for authenticating a client.\n   */\n  authenticate(): AuthHeaders;\n}\n\nexport class BasicAuthClientProvider implements ClientAuthProvider {\n  private readonly credentials: AuthHeaders;\n\n  /**\n   * Creates a new BasicAuthClientProvider.\n   * @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.\n   * @throws {Error} If neither credentials provider or text credentials are supplied.\n   */\n  constructor(textCredentials: string | undefined) {\n    const creds = textCredentials ?? process.env.CHROMA_CLIENT_AUTH_CREDENTIALS;\n    if (creds === undefined) {\n      throw new Error(\n        \"Credentials must be supplied via environment variable (CHROMA_CLIENT_AUTH_CREDENTIALS) or passed in as configuration.\",\n      );\n    }\n    this.credentials = {\n      Authorization: \"Basic \" + base64Encode(creds),\n    };\n  }\n\n  authenticate(): AuthHeaders {\n    return this.credentials;\n  }\n}\n\nexport class TokenAuthClientProvider implements ClientAuthProvider {\n  private readonly credentials: AuthHeaders;\n\n  constructor(\n    textCredentials: any,","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/auth.ts#L26-L62","documentation":"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.","triggerScenarios":"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').","commonSituations":"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.","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."],"exampleFix":"// before\nconst auth = new BasicAuthClientProvider(undefined); // env var not set in CI\n\n// after\nimport 'dotenv/config'; // ensure .env is loaded first\nconst auth = new BasicAuthClientProvider(process.env.CHROMA_CLIENT_AUTH_CREDENTIALS!);","handlingStrategy":"validation","validationCode":"const creds =\n  explicitCredentials ?? process.env.CHROMA_CLIENT_AUTH_CREDENTIALS;\nif (creds === undefined) {\n  throw new Error('Missing Chroma credentials: set CHROMA_CLIENT_AUTH_CREDENTIALS=user:password');\n}\nconst provider = new BasicAuthClientProvider(creds);","typeGuard":null,"tryCatchPattern":"try {\n  new BasicAuthClientProvider(creds);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('CHROMA_CLIENT_AUTH_CREDENTIALS')) {\n    // fail startup with an actionable message; do not swallow and continue unauthenticated\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["auth","credentials","environment-variable","basic-auth"],"backgroundTag":"missing-credentials","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}