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

The constructor resolves its API key as api_key or os.getenv(api_key_env_var), where api_key_env_var is forced to CLOUDFLARE_API_KEY if that variable is set, otherwise the name you passed (default CHROMA_CLOUDFLARE_API_KEY). With neither a key argument nor a populated variable it refuses to build the client. Passing api_key directly still works but emits a DeprecationWarning because raw keys are not persisted in the function config.

Source

Thrown at chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py:66

        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,
            )
        self.model_name = model_name
        self.account_id = account_id

        if os.getenv("CLOUDFLARE_API_KEY") is not None:
            self.api_key_env_var = "CLOUDFLARE_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)
        self.gateway_id = gateway_id

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

        if self.gateway_id:
            self._api_url = f"{GATEWAY_BASE_URL}/{self.account_id}/{self.gateway_id}/workers-ai/{self.model_name}"
        else:
            self._api_url = f"{BASE_URL}/{self.account_id}/ai/run/{self.model_name}"

        self._session = httpx.Client()
        self._session.headers.update(
            {"Authorization": f"Bearer {self.api_key}", "Accept-Encoding": "identity"}
        )

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

        Args:

View on GitHub (pinned to aecdd12c8a)

Solutions

1. export CLOUDFLARE_API_KEY=<key> - the constructor auto-detects it - or export the exact variable named in the error message.
2. Call load_dotenv() before constructing the embedding function if the key lives in a .env file.
3. For quick tests only, pass api_key='...' programmatically; note this raises a DeprecationWarning and will not survive config persistence.

Example fix

# before
# shell: CLOUDFLARE_API_KEY and CHROMA_CLOUDFLARE_API_KEY unset
ef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')  # ValueError

# after
from dotenv import load_dotenv
load_dotenv()  # .env: CLOUDFLARE_API_KEY=...
ef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')

import os
if not (os.getenv('CLOUDFLARE_API_KEY') or os.getenv('CHROMA_CLOUDFLARE_API_KEY')):
    raise SystemExit('Cloudflare credential missing: set CLOUDFLARE_API_KEY (auto-detected) before constructing the EF')

try:
    ef = CloudflareWorkersAIEmbeddingFunction(model_name=M, account_id=A)
except ValueError as e:
    if 'environment variable is not set' in str(e):
        raise SystemExit(f'Missing credential: {e}') from e
    raise

When it happens

Trigger: Constructing CloudflareWorkersAIEmbeddingFunction with no api_key= argument while neither CLOUDFLARE_API_KEY nor CHROMA_CLOUDFLARE_API_KEY (or your custom api_key_env_var) is exported in the process environment - fresh shell, CI runner, container, cron job.

Common situations: Key lives in .env but load_dotenv() was never called; the variable is exported under a different name than api_key_env_var; the secret was added to a different platform/environment than the one actually running the app.

Related errors

• Cloudflare API key is required. Please provide it in the con
• The {self.api_key_env_var} environment variable is not set.
• Cohere API key is required. Please provide it in the constru
• The {self.api_key_env_var} environment variable must be set
• The {self.api_key_env_var} environment variable is not set.

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