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

MorphEmbeddingFunction resolves its key as api_key or os.getenv(api_key_env_var) (default 'MORPH_API_KEY') in __init__ and raises this ValueError when neither is available. The Morph API requires authentication for the embeddings endpoint, so construction aborts. Passing api_key directly is deprecated (warned) in favor of the env var.

Source

Thrown at chromadb/utils/embedding_functions/morph_embedding_function.py:51

        try:
            import openai
        except ImportError:
            raise ValueError(
                "The openai python package is not installed. Please install it with `pip install openai`. "
                "Note: Morph uses the OpenAI client library for API communication."
            )

        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.api_key_env_var = api_key_env_var
        self.api_key = api_key or os.getenv(api_key_env_var)
        if not self.api_key:
            raise ValueError(f"The {api_key_env_var} environment variable is not set.")

        self.model_name = model_name
        self.api_base = api_base
        self.encoding_format = encoding_format

        # Initialize the OpenAI client with Morph's base URL
        self.client = openai.OpenAI(
            api_key=self.api_key,
            base_url=self.api_base,
        )

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

        Args:
            input: Documents to generate embeddings for.

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. export MORPH_API_KEY=... before constructing the EF
  2. Or use a custom variable: MorphEmbeddingFunction(api_key_env_var='MY_MORPH_KEY') with that var set
  3. load_dotenv() before EF construction when the key lives in .env
  4. Preflight check: python -c "import os; print(bool(os.getenv('MORPH_API_KEY')))"

Example fix

# before
from chromadb.utils.embedding_functions import MorphEmbeddingFunction
ef = MorphEmbeddingFunction()  # ValueError: MORPH_API_KEY not set

# after
import os
from dotenv import load_dotenv
load_dotenv()
assert os.getenv("MORPH_API_KEY"), "MORPH_API_KEY missing"
ef = MorphEmbeddingFunction()
Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.getenv("MORPH_API_KEY"):
    raise SystemExit("MORPH_API_KEY is required for MorphEmbeddingFunction")

from chromadb.utils.embedding_functions import MorphEmbeddingFunction
ef = MorphEmbeddingFunction()

Try / catch

try:
    ef = MorphEmbeddingFunction()
except ValueError as e:
    if "environment variable is not set" in str(e):
        raise RuntimeError("Set MORPH_API_KEY in the deployment environment") from e
    raise

Prevention

When it happens

Trigger: MorphEmbeddingFunction() with MORPH_API_KEY unset; deployments (docker/k8s/CI) where the secret env var was not injected; typos like MORPH_APIKEY; .env loaded after EF construction.

Common situations: Containerized apps missing secret env passthrough; team members with keys in personal shells but launching via IDE/daemon; rotating to a custom var name without updating api_key_env_var.

Related errors

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