chroma-core/chroma · error · ValueError

The {api_key_env_var} environment variable is not set.

Error message

The {api_key_env_var} environment variable is not set.

What it means

NomicEmbeddingFunction.__init__ reads the API key with os.getenv(api_key_env_var) (default variable name "NOMIC_API_KEY") and raises ValueError when the value is falsy. This fires at construction time, before any embedding call, because the Nomic client needs the key to authenticate against the Nomic Atlas API. Note that an empty string counts as unset, since the check is `if not self.api_key`.

Source

Thrown at chromadb/utils/embedding_functions/nomic_embedding_function.py:53

            query_config (Optional[NomicQueryConfig]): The configuration for setting task type for queries
            api_key_env_var (str): The environment variable name for the Nomic API key. Defaults to "NOMIC_API_KEY".

            Supported task types: search_document, search_query, classification, clustering
        """
        try:
            from nomic import embed
        except ImportError:
            raise ValueError(
                "The nomic python package is not installed. Please install it with `pip install nomic`"
            )

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

    def __call__(self, input: Documents) -> Embeddings:
        if not all(isinstance(item, str) for item in input):
            raise ValueError("Nomic only supports text documents, not images")
        output = self.embed.text(
            model=self.model,
            texts=input,
            task_type=self.task_type,
        )
        return [np.array(data.embedding) for data in output.data]

    def embed_query(self, input: Documents) -> Embeddings:
        if not all(isinstance(item, str) for item in input):
            raise ValueError("Nomic only supports text queries, not images")

        task_type = (
            self.query_config.get("task_type") if self.query_config else self.task_type

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Export the variable before starting Python: export NOMIC_API_KEY="nk-..." (get a key from the Nomic Atlas dashboard)
2. If you use a different variable name, pass it explicitly and verify it exists: NomicEmbeddingFunction(..., api_key_env_var="MY_NOMIC_KEY") after export MY_NOMIC_KEY=...
3. In docker-compose/Kubernetes, add the variable to the environment/env section of the service spec
4. For .env files, load them before construction: from dotenv import load_dotenv; load_dotenv()

Example fix

// before (KeyError-free but crashes at runtime)
fn = NomicEmbeddingFunction(model="nomic-embed-text-v1.5", task_type="search_query", query_config={"task_type": "search_query"})  # NOMIC_API_KEY not set -> ValueError

// after
import os
from dotenv import load_dotenv
load_dotenv()  # loads NOMIC_API_KEY from .env
if not os.getenv("NOMIC_API_KEY"):
    raise SystemExit("Set NOMIC_API_KEY before running")
fn = NomicEmbeddingFunction(model="nomic-embed-text-v1.5", task_type="search_query", query_config={"task_type": "search_query"})

import os
name = "NOMIC_API_KEY"  # or your custom api_key_env_var
if not os.getenv(name):
    raise SystemExit(f"Missing required env var {name}; export it before starting.")
fn = NomicEmbeddingFunction(model="nomic-embed-text-v1.5", task_type="search_document", query_config={"task_type": "search_query"}, api_key_env_var=name)

try:
    fn = NomicEmbeddingFunction(model=..., task_type=..., query_config=...)
except ValueError as e:
    if "environment variable is not set" in str(e):
        raise SystemExit("Nomic API key missing — set NOMIC_API_KEY and restart") from e
    raise

When it happens

Trigger: Instantiating NomicEmbeddingFunction(model=..., task_type=..., query_config=...) in a shell/process where NOMIC_API_KEY is not exported; passing a custom api_key_env_var (e.g. "MY_NOMIC_KEY") that does not exist; setting the variable to an empty string (export NOMIC_API_KEY=""); running under systemd/docker/cron where the env var was only set in an interactive shell.

Common situations: CI pipelines and Docker containers that strip environment variables; deploying to production where the key is stored in a secrets manager but never exported; typos in the custom env var name; scripts that read the key from .env but forget to load python-dotenv before constructing the EF.

Related errors

• The {self.api_key_env_var} environment variable is not set.
• The {self.api_key_env_var} environment variable is not set.
• The {self.api_key_env_var} environment variable must be set
• The {self.api_key_env_var} environment variable is not set.
• Nomic only supports text documents, not images

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