chroma-core/chroma · error · ValueError

API key not found in environment variable {api_key_env_var}

Error message

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

What it means

ChromaCloudQwenEmbeddingFunction resolves credentials in two steps: os.getenv(api_key_env_var) (default 'CHROMA_API_KEY'), then a fallback that asks SharedSystemClient.get_chroma_cloud_api_key_from_clients() for the key of any already-authenticated Chroma client in the process. If both come up empty it raises ValueError with the env var name, because every request to the Chroma Embed API needs the x-chroma-token header built from this key.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py:68

                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(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 {api_key_env_var} "
                f"or in any existing client instances"
            )

        self.model = model
        self.task = task
        self.instructions = instructions

        self._api_url = get_chroma_embed_url()
        self._session = httpx.Client()
        self._session.headers.update(
            {
                "x-chroma-token": self.api_key,
                "x-chroma-embedding-model": self.model.value,
            }
        )

    def _parse_response(self, response: Any) -> Embeddings:

View on GitHub (pinned to aecdd12c8a)

Solutions

export CHROMA_API_KEY=<your key> (or the value of the api_key_env_var you configured) in the environment that runs the process.
If you pass api_key_env_var, make sure it exactly matches the exported variable name (e.g. QWEN_EMBED_KEY).
Alternatively create an authenticated Chroma client first — its API key is picked up from existing client instances.
For .env-based setups, load variables before constructing the embedding function (e.g. dotenv.load_dotenv() at startup).

Example fix

# before
ef = ChromaCloudQwenEmbeddingFunction(
    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,
    task=None,
    api_key_env_var="QWEN_KEY",  # QWEN_KEY not exported -> ValueError
)

# after
# export QWEN_KEY="ck-..."
ef = ChromaCloudQwenEmbeddingFunction(
    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,
    task=None,
    api_key_env_var="QWEN_KEY",
)

Defensive patterns

Strategy: validation

Validate before calling

import os

API_KEY_ENV_VAR = "CHROMA_API_KEY"  # match the api_key_env_var you will pass
if not os.getenv(API_KEY_ENV_VAR):
    raise SystemExit(f"Export {API_KEY_ENV_VAR} before creating ChromaCloudQwenEmbeddingFunction")
ef = ChromaCloudQwenEmbeddingFunction(model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B, task=None, api_key_env_var=API_KEY_ENV_VAR)

Try / catch

try:
    ef = ChromaCloudQwenEmbeddingFunction(...)
except ValueError as e:
    if "API key not found" in str(e):
        # prompt for the key / load from secret manager, then construct again
        raise

Prevention

Check os.getenv(api_key_env_var) at application startup, before any client or EF construction.
Keep one constant for the env var name and reuse it for both the export and the constructor argument.
In containers, assert required env vars in the entrypoint so misconfigured deploys fail immediately.

When it happens

Trigger: Constructing the function when CHROMA_API_KEY (or the custom api_key_env_var you passed) is unset/empty AND no PersistentClient/HttpClient with a Chroma Cloud credential exists in-process. Example: passing api_key_env_var="QWEN_KEY" while only CHROMA_API_KEY is exported.

Common situations: Local script works (env var in shell) but the same code fails in cron/Docker/CI where the var was never exported; custom api_key_env_var name that does not match the actual environment; API key set only after the EF was constructed; secrets loaded via .env file that was never sourced.

Related errors

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