chroma-core/chroma · error · ValueError

The {self.api_key_env_var} environment variable must be set

Error message

The {self.api_key_env_var} environment variable must be set if vertexai is not enabled.

What it means

Raised in GoogleGeminiEmbeddingFunction.__init__ when no API key is found AND vertexai is falsy. The class reads the key with os.getenv(api_key_env_var) (default 'GEMINI_API_KEY') at construction time; if the variable is unset and Vertex mode is not enabled there is no credential for genai.Client, so initialization stops. The actual message interpolates the env var name that was checked.

Source

Thrown at chromadb/utils/embedding_functions/google_embedding_function.py:63

        except ImportError:
            raise ValueError(
                "The google-genai python package is not installed. Please install it with `pip install google-genai`"
            )

        self.model_name = model_name
        self.task_type = task_type
        self.dimension = dimension
        self.api_key_env_var = api_key_env_var
        self.vertexai = vertexai
        self.project = project
        self.location = location
        self.api_key = os.getenv(self.api_key_env_var) if self.api_key_env_var else None
        if self.api_key and self.vertexai:
            raise ValueError(
                "Vertex AI and API key are mutually exclusive in the client initializer."
            )
        if not self.api_key and not self.vertexai:
            raise ValueError(
                f"The {self.api_key_env_var} environment variable must be set if vertexai is not enabled."
            )

        from google.genai import types

        self.client = genai.Client(
            api_key=self.api_key,
            vertexai=vertexai,
            project=project,
            location=location,
            http_options=types.HttpOptions(
                headers={"x-goog-api-client": f"chroma/{__version__}"}
            ),
        )

    def __call__(self, input: Documents) -> Embeddings:
        """
        Generate embeddings for the given documents.

View on GitHub (pinned to aecdd12c8a)

Solutions

Export the variable in the process that runs Chroma: export GEMINI_API_KEY=...
Make api_key_env_var match the variable you actually set (e.g. pass api_key_env_var='GOOGLE_API_KEY' if that is what your secret store injects)
Call load_dotenv() before constructing the embedding function if the key lives in .env
If you are on GCP with service-account/ADC auth, construct with vertexai=True plus project and location instead of a key

Example fix

# before
import os
# GEMINI_API_KEY not set in this process
from chromadb.utils.embedding_functions import GoogleGeminiEmbeddingFunction
ef = GoogleGeminiEmbeddingFunction()  # ValueError: The GEMINI_API_KEY environment variable must be set...

# after
from dotenv import load_dotenv
load_dotenv()  # .env contains GEMINI_API_KEY=...
from chromadb.utils.embedding_functions import GoogleGeminiEmbeddingFunction
ef = GoogleGeminiEmbeddingFunction()

Defensive patterns

Strategy: validation

Validate before calling

import os

API_KEY_ENV = "GEMINI_API_KEY"

if not os.getenv(API_KEY_ENV):
    raise SystemExit(
        f"Set {API_KEY_ENV} (or pass api_key_env_var / vertexai=True for ADC) before starting"
    )

from chromadb.utils.embedding_functions import GoogleGeminiEmbeddingFunction
ef = GoogleGeminiEmbeddingFunction(api_key_env_var=API_KEY_ENV)

Try / catch

try:
    ef = GoogleGeminiEmbeddingFunction()
except ValueError as e:
    if "environment variable" in str(e):
        # config error, not transient - surface to operator
        raise SystemExit(f"Embedding auth not configured: {e}") from e
    raise

Prevention

Fail fast at process start: assert the env var exists before any embedding work
Load .env with python-dotenv at entrypoint, not after client construction
In containers, declare the env var explicitly (ENV/compose 'environment') so a missing secret is visible in config, not at runtime

When it happens

Trigger: Constructing GoogleGeminiEmbeddingFunction() with GEMINI_API_KEY absent; passing api_key_env_var='GOOGLE_API_KEY' when only GEMINI_API_KEY is exported (or vice versa); the variable existing in your shell but not in the Python process (systemd unit, docker exec, cron, IDE run configuration); a .env file that was never loaded; passing vertexai=False/None while intending to use Application Default Credentials.

Common situations: Works locally, fails when deployed because the secret was not propagated to docker-compose/Kubernetes/cron; key stored in .env but python-dotenv's load_dotenv() never called; renamed env var between environments; relying on GCP ADC without flipping vertexai=True.

Related errors

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