chroma-core/chroma · error · Error

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

Error message

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

What it means

OpenAIEmbeddingFunction requires an API key at construction: the explicit openai_api_key parameter or the environment variable named by openai_api_key_env_var, which defaults to CHROMA_OPENAI_API_KEY — not the conventional OPENAI_API_KEY. If neither yields a truthy string the constructor throws synchronously, before any network call.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts:110

  private openaiApi?: OpenAIAPI;
  private dimensions?: number;

  constructor({
    openai_api_key,
    openai_model = "text-embedding-ada-002",
    openai_organization_id,
    openai_embedding_dimensions,
    openai_api_key_env_var = "CHROMA_OPENAI_API_KEY",
  }: {
    openai_api_key?: string;
    openai_model?: string;
    openai_organization_id?: string;
    openai_embedding_dimensions?: number;
    openai_api_key_env_var?: string;
  }) {
    const apiKey = openai_api_key ?? process.env[openai_api_key_env_var];
    if (!apiKey) {
      throw new Error(
        `OpenAI API key is required. Please provide it in the constructor or set the environment variable ${openai_api_key_env_var}.`,
      );
    }
    this.api_key = apiKey;

    this.org_id = openai_organization_id ?? "";
    this.model = openai_model;
    this.dimensions = openai_embedding_dimensions ?? 1536;
  }

  private async loadClient() {
    // cache the client
    if (this.openaiApi) return;

    try {
      const { openai, version } = await OpenAIEmbeddingFunction.import();
      OpenAIApi = openai;
      let versionVar: string = version;

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the key explicitly (most robust): new OpenAIEmbeddingFunction({ openai_api_key: process.env.OPENAI_API_KEY!, openai_model: "text-embedding-3-small" })
Or export CHROMA_OPENAI_API_KEY=... to match the default env var name
Or point at your existing variable: openai_api_key_env_var: "OPENAI_API_KEY" with that variable exported
Verify inside the process: node -e "console.log(!!process.env.CHROMA_OPENAI_API_KEY)"

Example fix

// before: throws — default env var name is CHROMA_OPENAI_API_KEY
const ef = new OpenAIEmbeddingFunction({ openai_model: "text-embedding-3-small" });

// after: either export CHROMA_OPENAI_API_KEY, or be explicit
const ef = new OpenAIEmbeddingFunction({
  openai_api_key: process.env.OPENAI_API_KEY!,
  openai_api_key_env_var: "OPENAI_API_KEY",
  openai_model: "text-embedding-3-small",
});

Defensive patterns

Strategy: validation

Validate before calling

function requireEnv(name: string): string {
  const v = process.env[name];
  if (!v) throw new Error(`Missing required env var ${name}`);
  return v;
}
// before constructing — note the non-default name CHROMA_OPENAI_API_KEY:
const openai_api_key = requireEnv("OPENAI_API_KEY");
const ef = new OpenAIEmbeddingFunction({ openai_api_key, openai_api_key_env_var: "OPENAI_API_KEY", openai_model: "text-embedding-3-small" });

Try / catch

try {
  ef = new OpenAIEmbeddingFunction({ openai_model: "text-embedding-3-small" });
} catch (e) {
  if (e instanceof Error && e.message.includes("API key is required")) {
    // config error: mention CHROMA_OPENAI_API_KEY (the default name) in the ops message; do not retry
  }
  throw e;
}

Prevention

Pass openai_api_key explicitly instead of relying on the CHROMA_OPENAI_API_KEY default
Check env var names at boot with a single validation step; the chroma default differs from OPENAI_API_KEY
Load dotenv before constructing any embedding function

When it happens

Trigger: new OpenAIEmbeddingFunction({ openai_model: "text-embedding-3-small" }) with CHROMA_OPENAI_API_KEY unset and no openai_api_key passed; or setting openai_api_key_env_var: "OPENAI_API_KEY" while that variable is absent.

Common situations: Assuming the standard OPENAI_API_KEY name is read (it is not, by default); dotenv loaded after client construction; CI/containers missing the secret; the key provided only via organization-level config and never exported.

Related errors

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