{"record":{"id":"eab293099998f4d4","repo":"chroma-core/chroma","slug":"openai-api-key-is-required-please-provide-it-in-t","errorCode":null,"errorMessage":"OpenAI API key is required. Please provide it in the constructor or set the environment variable ${openai_api_key_env_var}.","messagePattern":"OpenAI API key is required\\. Please provide it in the constructor or set the environment variable (.+?)\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts","lineNumber":110,"sourceCode":"  private openaiApi?: OpenAIAPI;\n  private dimensions?: number;\n\n  constructor({\n    openai_api_key,\n    openai_model = \"text-embedding-ada-002\",\n    openai_organization_id,\n    openai_embedding_dimensions,\n    openai_api_key_env_var = \"CHROMA_OPENAI_API_KEY\",\n  }: {\n    openai_api_key?: string;\n    openai_model?: string;\n    openai_organization_id?: string;\n    openai_embedding_dimensions?: number;\n    openai_api_key_env_var?: string;\n  }) {\n    const apiKey = openai_api_key ?? process.env[openai_api_key_env_var];\n    if (!apiKey) {\n      throw new Error(\n        `OpenAI API key is required. Please provide it in the constructor or set the environment variable ${openai_api_key_env_var}.`,\n      );\n    }\n    this.api_key = apiKey;\n\n    this.org_id = openai_organization_id ?? \"\";\n    this.model = openai_model;\n    this.dimensions = openai_embedding_dimensions ?? 1536;\n  }\n\n  private async loadClient() {\n    // cache the client\n    if (this.openaiApi) return;\n\n    try {\n      const { openai, version } = await OpenAIEmbeddingFunction.import();\n      OpenAIApi = openai;\n      let versionVar: string = version;","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts#L92-L128","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)\""],"exampleFix":"// before: throws — default env var name is CHROMA_OPENAI_API_KEY\nconst ef = new OpenAIEmbeddingFunction({ openai_model: \"text-embedding-3-small\" });\n\n// after: either export CHROMA_OPENAI_API_KEY, or be explicit\nconst ef = new OpenAIEmbeddingFunction({\n  openai_api_key: process.env.OPENAI_API_KEY!,\n  openai_api_key_env_var: \"OPENAI_API_KEY\",\n  openai_model: \"text-embedding-3-small\",\n});","handlingStrategy":"validation","validationCode":"function requireEnv(name: string): string {\n  const v = process.env[name];\n  if (!v) throw new Error(`Missing required env var ${name}`);\n  return v;\n}\n// before constructing — note the non-default name CHROMA_OPENAI_API_KEY:\nconst openai_api_key = requireEnv(\"OPENAI_API_KEY\");\nconst ef = new OpenAIEmbeddingFunction({ openai_api_key, openai_api_key_env_var: \"OPENAI_API_KEY\", openai_model: \"text-embedding-3-small\" });","typeGuard":null,"tryCatchPattern":"try {\n  ef = new OpenAIEmbeddingFunction({ openai_model: \"text-embedding-3-small\" });\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"API key is required\")) {\n    // config error: mention CHROMA_OPENAI_API_KEY (the default name) in the ops message; do not retry\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["api-key","env-var","openai","configuration","embeddings"],"backgroundTag":"missing-api-key","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}