rohitg00/agentmemory · error · Error

GEMINI_API_KEY is required

Error message

GEMINI_API_KEY is required

What it means

The Gemini embedding provider's constructor requires an API key from the `apiKey` argument or the GEMINI_API_KEY env var, and throws at construction if neither yields a non-empty value. This is fail-fast validation so misconfiguration is caught before any network call is attempted.

Source

Thrown at src/providers/embedding/gemini.ts:16

import type { EmbeddingProvider } from "../../types.js";
import { getEnvVar } from "../../config.js";
import { fetchWithTimeout } from "../_fetch.js";

const BATCH_LIMIT = 100;
const MODEL = "models/gemini-embedding-001";
const API_BASE = `https://generativelanguage.googleapis.com/v1beta/${MODEL}:batchEmbedContents`;

export class GeminiEmbeddingProvider implements EmbeddingProvider {
  readonly name = "gemini";
  readonly dimensions = 768;
  private apiKey: string;

  constructor(apiKey?: string) {
    this.apiKey = apiKey || getEnvVar("GEMINI_API_KEY") || "";
    if (!this.apiKey) throw new Error("GEMINI_API_KEY is required");
  }

  async embed(text: string): Promise<Float32Array> {
    const [result] = await this.embedBatch([text]);
    return result;
  }

  async embedBatch(texts: string[]): Promise<Float32Array[]> {
    const results: Float32Array[] = [];

    for (let i = 0; i < texts.length; i += BATCH_LIMIT) {
      const chunk = texts.slice(i, i + BATCH_LIMIT);
      const response = await fetchWithTimeout(`${API_BASE}?key=${this.apiKey}`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          requests: chunk.map((t) => ({
            model: MODEL,

View on GitHub (pinned to e04ba88819)

Solutions

1. Export the key: `export GEMINI_API_KEY=your-key` (create one at aistudio.google.com/apikey).
2. Pass the key explicitly to the constructor once confirmed non-empty: `new GeminiProvider(process.env.GEMINI_API_KEY)`.
3. Confirm the exact variable name GEMINI_API_KEY and that env loading (dotenv/.env file) happens before the provider module is imported.
4. If you didn't intend Gemini, configure/construct a different embedding provider instead.

Example fix

// before
const provider = new GeminiProvider(); // throws: GEMINI_API_KEY is required
// after
// .env: GEMINI_API_KEY=AIza...
require("dotenv").config();
const provider = new GeminiProvider(process.env.GEMINI_API_KEY);

function requireEnv(name: string): string {
  const v = process.env[name];
  if (!v || v.trim() === "") throw new Error(`${name} is not set`);
  return v.trim();
}
const key = requireEnv("GEMINI_API_KEY"); // run before constructing GeminiProvider

function hasApiKey(v: unknown): v is string {
  return typeof v === "string" && v.trim().length > 0;
}

try {
  provider = new GeminiProvider();
} catch (e) {
  if (e instanceof Error && e.message === "GEMINI_API_KEY is required") {
    console.error("Set GEMINI_API_KEY (Google AI Studio) before starting");
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Instantiating the Gemini embedding provider with no explicit key while GEMINI_API_KEY is unset, empty, or whitespace — e.g. after a fresh checkout, a container image without the secret mounted, or a renamed env variable.

Common situations: Google AI Studio key never created or exported; secret not injected into the deployment (k8s secret missing, CI env not configured); using GOOGLE_API_KEY or GEMINI_KEY naming instead of GEMINI_API_KEY; dotenv loading after provider construction at module import time.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• COHERE_API_KEY is required
• API key is required (via constructor, OPENAI_EMBEDDING_API_K
• OPENROUTER_API_KEY is required
• VOYAGE_API_KEY is required
• GEMINI_API_KEY (or GOOGLE_API_KEY) is required for the gemin

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/00567da6bb88d408. Report an issue: GitHub.