chroma-core/chroma · error · ValueError

The {self.api_key_env_var} environment variable is not set.

Error message

The {self.api_key_env_var} environment variable is not set.

What it means

OpenAIEmbeddingFunction.__init__ raises this ValueError when no API key can be resolved: the api_key argument was not passed and os.getenv(api_key_env_var) is empty/unset. The env var name defaults to OPENAI_API_KEY, but note the constructor forces self.api_key_env_var to "OPENAI_API_KEY" whenever that variable is set, otherwise it uses the api_key_env_var parameter. Construction fails immediately, before any embeddings are requested.

Source

Thrown at chromadb/utils/embedding_functions/openai_embedding_function.py:67

            raise ValueError(
                "The openai python package is not installed. Please install it with `pip install openai`"
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )

        if os.getenv("OPENAI_API_KEY") is not None:
            self.api_key_env_var = "OPENAI_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)
        if not self.api_key:
            raise ValueError(
                f"The {self.api_key_env_var} environment variable is not set."
            )

        self.model_name = model_name
        self.organization_id = organization_id
        self.api_base = api_base
        self.api_type = api_type
        self.api_version = api_version
        self.deployment_id = deployment_id
        self.default_headers = default_headers
        self.dimensions = dimensions

        # Initialize the OpenAI client
        client_params: Dict[str, Any] = {"api_key": self.api_key}

        if self.organization_id is not None:
            client_params["organization"] = self.organization_id
        if self.api_base is not None:

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Set the environment variable before constructing: export OPENAI_API_KEY=sk-... (or the custom name you passed to api_key_env_var), and verify with echo $OPENAI_API_KEY in the same environment that runs the app.
  2. If the key is empty in env, pass it explicitly: OpenAIEmbeddingFunction(api_key="sk-...") — note this now emits a DeprecationWarning because direct api_key is not persisted in collection metadata.
  3. If you use a custom variable name, make sure it matches what is actually exported: OpenAIEmbeddingFunction(api_key_env_var="MY_OPENAI_KEY") requires export MY_OPENAI_KEY=...
  4. In docker-compose/Kubernetes, add the variable to environment: or envFrom: and restart the pod/container; in CI, add it to the pipeline's secret variables.
  5. If loading from .env, call load_dotenv() before creating the embedding function, not after.

Example fix

// before
import chromadb.utils.embedding_functions as ef
openai_ef = ef.OpenAIEmbeddingFunction()  # ValueError: The OPENAI_API_KEY environment variable is not set.

# after
import os
from dotenv import load_dotenv
load_dotenv()  # ensure .env is loaded first
if not os.getenv("OPENAI_API_KEY"):
    raise RuntimeError("OPENAI_API_KEY missing — check your secrets setup")
openai_ef = ef.OpenAIEmbeddingFunction(model_name="text-embedding-3-small")
Defensive patterns

Strategy: validation

Validate before calling

import os

OPENAI_EF_ENV = os.getenv("OPENAI_API_KEY_ENV_VAR", "OPENAI_API_KEY")
if not os.getenv(OPENAI_EF_ENV):
    raise RuntimeError(
        f"{OPENAI_EF_ENV} is not set — export it before creating OpenAIEmbeddingFunction"
    )
# safe to construct now
openai_ef = OpenAIEmbeddingFunction()

Type guard

def has_openai_api_key(env_var: str = "OPENAI_API_KEY") -> bool:
    return bool(os.getenv(env_var))

Try / catch

try:
    openai_ef = OpenAIEmbeddingFunction()
except ValueError as e:
    if "environment variable is not set" in str(e):
        raise RuntimeError(f"Missing OpenAI credentials: {e}") from e
    raise

Prevention

When it happens

Trigger: Calling OpenAIEmbeddingFunction() (or passing it as embedding_function= to Client/CreateCollection) in a process where OPENAI_API_KEY is unset and no api_key or custom api_key_env_var with a set variable is provided. Also happens when a custom api_key_env_var is passed but that variable is empty, and when code that worked locally (env var in shell) runs under cron/CI/docker where the variable was never exported.

Common situations: Forgetting to export OPENAI_API_KEY in the shell or Docker image; using a secrets manager (dotenv, Vault, pydantic-settings) but loading it after constructing the embedding function; passing api_key_env_var="MY_KEY" while only OPENAI_API_KEY is set is fine, but the reverse (custom name, unset value) fails; .env file present but python-dotenv load_dotenv() never called.

Related errors

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