{"record":{"id":"61e150b95eafcfbd","repo":"chroma-core/chroma","slug":"voyageai-api-key-is-required-please-provide-it-in","errorCode":null,"errorMessage":"VoyageAI API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.","messagePattern":"VoyageAI 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/VoyageAIEmbeddingFunction.ts","lineNumber":61,"sourceCode":"export class VoyageAIEmbeddingFunction implements IEmbeddingFunction {\n  name = \"voyageai\";\n\n  private voyageAiApi?: VoyageAIAPI;\n  private model: string;\n  private apiKey: string;\n  private apiKeyEnvVar: string;\n  constructor({\n    api_key,\n    model,\n    api_key_env_var = \"CHROMA_VOYAGE_API_KEY\",\n  }: {\n    api_key?: string;\n    model: string;\n    api_key_env_var: string;\n  }) {\n    const apiKey = api_key ?? process.env[api_key_env_var];\n    if (!apiKey) {\n      throw new Error(\n        `VoyageAI API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.`,\n      );\n    }\n    this.apiKey = apiKey;\n    this.model = model;\n    this.apiKeyEnvVar = api_key_env_var;\n  }\n\n  private async initClient() {\n    if (this.voyageAiApi) return;\n    try {\n      // @ts-ignore\n      this.voyageAiApi = await import(\"voyageai\").then((voyageai) => {\n        // @ts-ignore\n        return new VoyageAIAPI({ apiKey: this.apiKey });\n      });\n    } catch (e) {\n      // @ts-ignore","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/VoyageAIEmbeddingFunction.ts#L43-L79","documentation":"VoyageAIEmbeddingFunction's constructor requires an API key: it takes together... it resolves `api_key ?? process.env[api_key_env_var]` (default env var CHROMA_VOYAGE_API_KEY) and throws immediately at construction time when neither is present, before any network call. buildFromConfig() hits the same path when restoring a function from a stored collection config whose env var is unset.","triggerScenarios":"new VoyageAIEmbeddingFunction({ model: 'voyage-2' }) with CHROMA_VOYAGE_API_KEY not exported in the current shell/CI; passing a custom api_key_env_var whose variable is unset; buildFromConfig({ model_name, api_key_env_var: 'MY_KEY' }) where MY_KEY is not in the environment.","commonSituations":"dotenv not loaded before the Chroma client is constructed; env var set in dev shell but missing in Docker/CI/systemd; typo in the env var name; defaulting to api_key in tests but forgetting it in deploy config.","solutions":["Pass the key directly for a quick check: new VoyageAIEmbeddingFunction({ model, api_key: process.env.VOYAGE_KEY }).","Or export CHROMA_VOYAGE_API_KEY (or your custom api_key_env_var) in the environment that runs the process.","If using dotenv, ensure import 'dotenv/config' (or config()) runs before constructing the client.","Verify in the failing environment: node -e \"console.log(Boolean(process.env.CHROMA_VOYAGE_API_KEY))\"."],"exampleFix":"// before\nimport { ChromaClient } from \"chromadb\";\nconst client = new ChromaClient();\n// CHROMA_VOYAGE_API_KEY unset -> constructor throws\nconst fn = new VoyageAIEmbeddingFunction({ model: \"voyage-2\" });\n\n// after\nimport \"dotenv/config\"; // load .env first\nconst fn = new VoyageAIEmbeddingFunction({\n  model: \"voyage-2\",\n  api_key: process.env.VOYAGE_API_KEY,\n});","handlingStrategy":"validation","validationCode":"// Fail fast with your own message before constructing the client\nconst voyKey = process.env.CHROMA_VOYAGE_API_KEY;\nif (!voyKey) {\n  throw new Error(\"CHROMA_VOYAGE_API_KEY is not set — add it to .env / CI secrets before starting.\");\n}\nnew VoyageAIEmbeddingFunction({ model: \"voyage-2\", api_key: voyKey });","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Load dotenv before any Chroma import side effects construct embedding functions.","Add env-var presence checks to process bootstrapping so missing keys fail startup with actionable messages.","Prefer passing api_key explicitly in ephemeral environments (tests, one-off jobs)."],"tags":["voyageai","embeddings","api-key","env-var","configuration"],"backgroundTag":"missing-env-var","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}