chroma-core/chroma · error · ValueError

API key not found in environment variable {self.api_key_env_

Error message

API key not found in environment variable {self.api_key_env_var} or in any existing client instances

What it means

The SPLADE constructor resolves its API key by checking os.getenv(self.api_key_env_var) (default 'CHROMA_API_KEY') and then falling back to SharedSystemClient.get_chroma_cloud_api_key_from_clients(); if both are empty it raises ValueError. The key is required to set the x-chroma-token header on every /embed_sparse request.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py:49

            api_key_env_var (str, optional): Environment variable name that contains your API key.
                Defaults to "CHROMA_API_KEY".
        """
        try:
            import httpx
        except ImportError:
            raise ValueError(
                "The httpx python package is not installed. Please install it with `pip install httpx`"
            )
        self.api_key_env_var = api_key_env_var
        # First, try to get API key from environment variable
        self.api_key = os.getenv(self.api_key_env_var)
        # If not found in env var, try to get it from existing client instances
        if not self.api_key:
            SharedSystemClient = _get_shared_system_client()
            self.api_key = SharedSystemClient.get_chroma_cloud_api_key_from_clients()
        # Raise error if still no API key found
        if not self.api_key:
            raise ValueError(
                f"API key not found in environment variable {self.api_key_env_var} "
                f"or in any existing client instances"
            )
        self.model = model
        self.include_tokens = bool(include_tokens)
        self._api_url = f"{get_chroma_embed_url()}/embed_sparse"
        self._session = httpx.Client()
        self._session.headers.update(
            {
                "x-chroma-token": self.api_key,
                "x-chroma-embedding-model": self.model.value,
            }
        )

    def __del__(self) -> None:
        """
        Cleanup the HTTP client session when the object is destroyed.
        """

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Export the key: export CHROMA_API_KEY=... (or the exact name you passed as api_key_env_var).
2. Align the api_key_env_var argument with the real variable name in the deployment environment.
3. Or construct an authenticated Chroma client first — its key is discovered from existing client instances.
4. Load secrets (dotenv/vault) before instantiating the embedding function.

Example fix

# before
ef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var="SPLADE_KEY")  # ValueError: not found

# after
# export SPLADE_KEY="ck-..."
ef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var="SPLADE_KEY")

import os

API_KEY_ENV_VAR = "CHROMA_API_KEY"
if not os.getenv(API_KEY_ENV_VAR):
    raise SystemExit(f"Export {API_KEY_ENV_VAR} before creating ChromaCloudSpladeEmbeddingFunction")
ef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var=API_KEY_ENV_VAR)

try:
    ef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var="CHROMA_API_KEY")
except ValueError as e:
    if "API key not found" in str(e):
        # fetch from secret manager, os.environ[...] = key, then retry construction
        raise

When it happens

Trigger: Creating ChromaCloudSpladeEmbeddingFunction when the named env var is unset/empty and no authenticated Chroma client exists in-process; e.g. passing api_key_env_var="SPLADE_KEY" while the variable was never exported.

Common situations: Works locally, fails in Docker/cron/CI where env vars are not propagated; mismatch between the api_key_env_var argument and the actually exported name; key configured only in .env that is loaded after construction; forked worker processes losing the parent's clients.

Related errors

• API key not found in environment variable {api_key_env_var}
• api_key_env_var must be provided in config
• Cloudflare API key is required. Please provide it in the con
• Cohere API key is required. Please provide it in the constru
• Google API key is required. Please provide it in the constru

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