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 key as api_key or os.getenv(api_key_env_var), where api_key_env_var becomes COHERE_API_KEY automatically if that variable is set, otherwise the value you passed (default CHROMA_COHERE_API_KEY). With neither an explicit key nor any populated variable it raises this ValueError before creating cohere.Client. Passing api_key directly works but emits a DeprecationWarning since raw keys are not persisted.

Source

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

        except ImportError:
            raise ValueError(
                "The PIL python package is not installed. Please install it with `pip install pillow`"
            )

        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("COHERE_API_KEY") is not None:
            self.api_key_env_var = "COHERE_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.client = cohere.Client(self.api_key)

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

        Args:
            input: Documents or images to generate embeddings for.

        Returns:
            Embeddings for the documents.
        """

View on GitHub (pinned to aecdd12c8a)

Solutions

1. export COHERE_API_KEY=<key> - it is auto-detected by the constructor.
2. Or export CHROMA_COHERE_API_KEY (the default api_key_env_var) or your custom variable name exactly as passed.
3. Call load_dotenv() before constructing the function; for throwaway tests pass api_key='...' despite the DeprecationWarning.

Example fix

# before
from chromadb.utils.embedding_functions import CohereEmbeddingFunction
ef = CohereEmbeddingFunction()  # ValueError: CHROMA_COHERE_API_KEY is not set

# after
from dotenv import load_dotenv
load_dotenv()  # .env: COHERE_API_KEY=...
from chromadb.utils.embedding_functions import CohereEmbeddingFunction
ef = CohereEmbeddingFunction()  # auto-detects COHERE_API_KEY

import os
if not (os.getenv('COHERE_API_KEY') or os.getenv('CHROMA_COHERE_API_KEY')):
    raise SystemExit('Cohere credential missing: set COHERE_API_KEY (auto-detected) or CHROMA_COHERE_API_KEY')

try:
    ef = CohereEmbeddingFunction()
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 CohereEmbeddingFunction with no api_key= argument while neither COHERE_API_KEY nor CHROMA_COHERE_API_KEY (or your custom api_key_env_var) is set in the process environment.

Common situations: The key is in .env but load_dotenv() runs after the EF is created; CI/production secrets configured under a different variable name; local works (variable exported in .bashrc) but the container fails.

Related errors

• Cohere API key is required. Please provide it in the constru
• The {self.api_key_env_var} environment variable is not set.
• Cloudflare API key is required. Please provide it in the con
• 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/4963beeb63241ed5. Report an issue: GitHub.