chroma-core/chroma · error · Error

VoyageAI API key is required. Please provide it in the const

Error message

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

What it means

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.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/VoyageAIEmbeddingFunction.ts:61

export class VoyageAIEmbeddingFunction implements IEmbeddingFunction {
  name = "voyageai";

  private voyageAiApi?: VoyageAIAPI;
  private model: string;
  private apiKey: string;
  private apiKeyEnvVar: string;
  constructor({
    api_key,
    model,
    api_key_env_var = "CHROMA_VOYAGE_API_KEY",
  }: {
    api_key?: string;
    model: string;
    api_key_env_var: string;
  }) {
    const apiKey = api_key ?? process.env[api_key_env_var];
    if (!apiKey) {
      throw new Error(
        `VoyageAI API key is required. Please provide it in the constructor or set the environment variable ${api_key_env_var}.`,
      );
    }
    this.apiKey = apiKey;
    this.model = model;
    this.apiKeyEnvVar = api_key_env_var;
  }

  private async initClient() {
    if (this.voyageAiApi) return;
    try {
      // @ts-ignore
      this.voyageAiApi = await import("voyageai").then((voyageai) => {
        // @ts-ignore
        return new VoyageAIAPI({ apiKey: this.apiKey });
      });
    } catch (e) {
      // @ts-ignore

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Pass the key directly for a quick check: new VoyageAIEmbeddingFunction({ model, api_key: process.env.VOYAGE_KEY }).
2. Or export CHROMA_VOYAGE_API_KEY (or your custom api_key_env_var) in the environment that runs the process.
3. If using dotenv, ensure import 'dotenv/config' (or config()) runs before constructing the client.
4. Verify in the failing environment: node -e "console.log(Boolean(process.env.CHROMA_VOYAGE_API_KEY))".

Example fix

// before
import { ChromaClient } from "chromadb";
const client = new ChromaClient();
// CHROMA_VOYAGE_API_KEY unset -> constructor throws
const fn = new VoyageAIEmbeddingFunction({ model: "voyage-2" });

// after
import "dotenv/config"; // load .env first
const fn = new VoyageAIEmbeddingFunction({
  model: "voyage-2",
  api_key: process.env.VOYAGE_API_KEY,
});

// Fail fast with your own message before constructing the client
const voyKey = process.env.CHROMA_VOYAGE_API_KEY;
if (!voyKey) {
  throw new Error("CHROMA_VOYAGE_API_KEY is not set — add it to .env / CI secrets before starting.");
}
new VoyageAIEmbeddingFunction({ model: "voyage-2", api_key: voyKey });

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Google API key is required. Please provide it in the constru
• Jina AI API key is required. Please provide it in the constr
• OpenAI API key is required. Please provide it in the constru
• Together AI API key is required. Please provide it in the co
• Cloudflare API key is required. Please provide it in the con

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