chroma-core/chroma · error · Error

Cohere API key is required. Please provide it in the constru

Error message

Cohere API key is required. Please provide it in the constructor or set the environment variable ${cohere_api_key_env_var}.

What it means

CohereEmbeddingFunction resolves its key as cohere_api_key ?? process.env[cohere_api_key_env_var] (default 'CHROMA_COHERE_API_KEY') in the constructor and throws this Error when both are absent. The key is handed to the cohere-ai SDK on first use; only the env-var name is persisted in the collection config, so buildFromConfig restores require the variable to be set again.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/CohereEmbeddingFunction.ts:127

     * base64 encoded PNG data URIs.
     */
    isImage = false,
  }: {
    cohere_api_key?: string;
    model?: string;
    cohere_api_key_env_var: string;
    /**
     * If true, the input texts passed to `generate` are expected to be
     * base64 encoded PNG data URIs.
     */
    isImage?: boolean;
  }) {
    this.model = model;
    this.isImage = isImage;

    const apiKey = cohere_api_key ?? process.env[cohere_api_key_env_var];
    if (!apiKey) {
      throw new Error(
        `Cohere API key is required. Please provide it in the constructor or set the environment variable ${cohere_api_key_env_var}.`,
      );
    }

    this.apiKey = apiKey;
    this.apiKeyEnvVar = cohere_api_key_env_var;
  }

  private async initCohereClient() {
    if (this.cohereAiApi) return;
    try {
      // @ts-ignore
      this.cohereAiApi = await import("cohere-ai").then((cohere) => {
        // @ts-ignore
        if (cohere.CohereClient) {
          return new CohereAISDK7({ apiKey: this.apiKey });
        } else {
          return new CohereAISDK56({ apiKey: this.apiKey });

View on GitHub (pinned to aecdd12c8a)

Solutions

Export the env var: export CHROMA_COHERE_API_KEY='<cohere-key>'.
Or pass the key directly in the constructor: new CohereEmbeddingFunction({ model_name, cohere_api_key: process.env.COHERE_KEY }).
Add the secret to your platform's env config and log a presence check (not the value) at startup.

Example fix

// before
const ef = new CohereEmbeddingFunction({ model_name: 'embed-english-v3.0' });

// after
import 'dotenv/config';
const ef = new CohereEmbeddingFunction({
  model_name: 'embed-english-v3.0',
  cohere_api_key: process.env.CHROMA_COHERE_API_KEY,
});

Defensive patterns

Strategy: validation

Validate before calling

const cohereKey = process.env.CHROMA_COHERE_API_KEY;
if (!cohereKey) {
  throw new Error('Set CHROMA_COHERE_API_KEY (or pass cohere_api_key) before constructing CohereEmbeddingFunction');
}
const ef = new CohereEmbeddingFunction({ model_name: 'embed-english-v3.0', cohere_api_key: cohereKey });

Try / catch

try {
  new CohereEmbeddingFunction({ model_name });
} catch (e) {
  if (e instanceof Error && e.message.includes('Cohere API key is required')) {
    // add the secret to the environment (or constructor) and construct again
  }
  throw e;
}

Prevention

Assert the env var at startup rather than at first embed.
Load dotenv/config as the first import so the var exists before EF construction.
If you use a custom cohere_api_key_env_var, document it for every deployment stage.

When it happens

Trigger: new CohereEmbeddingFunction({ model_name: 'embed-english-v3.0' }) with CHROMA_COHERE_API_KEY unset; custom cohere_api_key_env_var never injected in the deploy environment; opening a collection configured with Cohere on a machine without the var.

Common situations: Local .env not loaded before constructing the EF; secret present in dev but missing in CI/prod; the env var was renamed during a migration but deployment templates still use the old name.

Related errors

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