chroma-core/chroma · error · Error

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

Error message

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

What it means

GoogleGenerativeAiEmbeddingFunction requires a Gemini API key at construction time: either the explicit googleApiKey parameter or the environment variable named by apiKeyEnvVar (default GOOGLE_API_KEY). If neither yields a truthy string the constructor throws synchronously — no network call is attempted, so this fails at client-setup time, not at embed time.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/GoogleGeminiEmbeddingFunction.ts:36

  private api_key_env_var: string;
  private model: string;
  private googleGenAiApi?: any;
  private taskType: string;

  constructor({
    googleApiKey,
    model = "embedding-001",
    taskType = "RETRIEVAL_DOCUMENT",
    apiKeyEnvVar = "GOOGLE_API_KEY",
  }: {
    googleApiKey?: string;
    model?: string;
    taskType?: string;
    apiKeyEnvVar: string;
  }) {
    const apiKey = googleApiKey ?? process.env[apiKeyEnvVar];
    if (!apiKey) {
      throw new Error(
        `Google API key is required. Please provide it in the constructor or set the environment variable ${apiKeyEnvVar}.`,
      );
    }

    this.api_key = apiKey;
    this.api_key_env_var = apiKeyEnvVar;
    this.model = model;
    this.taskType = taskType;
  }

  private async loadClient() {
    if (this.googleGenAiApi) return;
    try {
      // eslint-disable-next-line global-require,import/no-extraneous-dependencies
      const { googleGenAi } =
        await GoogleGenerativeAiEmbeddingFunction.import();
      googleGenAiApi = googleGenAi;
      // googleGenAiApi.init(this.api_key);

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass the key explicitly: new GoogleGenerativeAiEmbeddingFunction({ googleApiKey: process.env.GEMINI_API_KEY!, ... })
Or export the env var matching the configured name: export GOOGLE_API_KEY=... for the default
Verify visibility inside the running process: node -e "console.log(!!process.env.GOOGLE_API_KEY)"
Ensure import "dotenv/config" (or equivalent) runs before the embedding function is constructed

Example fix

// before
const ef = new GoogleGenerativeAiEmbeddingFunction({ model: "embedding-001", apiKeyEnvVar: "GOOGLE_API_KEY" }); // throws: env unset

// after
import "dotenv/config";
const ef = new GoogleGenerativeAiEmbeddingFunction({
  googleApiKey: process.env.GOOGLE_API_KEY!, // explicit; fails loudly at boot if missing
  model: "embedding-001",
});

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:
const googleApiKey = requireEnv("GOOGLE_API_KEY");
const ef = new GoogleGenerativeAiEmbeddingFunction({ googleApiKey, model: "embedding-001", apiKeyEnvVar: "GOOGLE_API_KEY" });

Try / catch

try {
  ef = new GoogleGenerativeAiEmbeddingFunction({ apiKeyEnvVar: "GOOGLE_API_KEY" });
} catch (e) {
  if (e instanceof Error && e.message.includes("API key is required")) {
    // configuration error: stop boot with an ops-facing message; do not retry
  }
  throw e;
}

Prevention

Validate every required env var at process start and fail fast before any work
Load dotenv at the entrypoint's first line, before any client construction
Keep env var names in one shared constants module so code and infra cannot drift

When it happens

Trigger: new GoogleGenerativeAiEmbeddingFunction({ model: "embedding-001", apiKeyEnvVar: "GOOGLE_API_KEY" }) with GOOGLE_API_KEY unset and no googleApiKey passed; or a custom apiKeyEnvVar name that does not match any exported variable (common in CI, cron, containers).

Common situations: dotenv loaded after the embedding function is constructed; custom apiKeyEnvVar name that differs from what ops exported; key present in a deploy secret but never exported into the process env; works locally (shell profile) but fails in systemd/CI where the profile is not sourced.

Related errors

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