chroma-core/chroma · error · ValueError

API key not provided and {self.api_key_env_var} environment

Error message

API key not provided and {self.api_key_env_var} environment variable is not set.

What it means

BasetenEmbeddingFunction resolves its API key from the api_key argument first (deprecated for persistence — it is never stored in get_config()), then from an environment variable. The env-var name is BASETEN_API_KEY if that is set, otherwise the api_key_env_var argument (default CHROMA_BASETEN_API_KEY). If neither the argument nor the resolved env var yields a key, this ValueError fires, naming the exact variable it checked. This is the expected path when a persisted config is rehydrated on a machine without credentials.

Source

Thrown at chromadb/utils/embedding_functions/baseten_embedding_function.py:47

                "The openai python package is not installed. Please install it with `pip install openai`"
            )

        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("BASETEN_API_KEY") is not None:
            self.api_key_env_var = "BASETEN_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        # Prioritize api_key argument, then environment variable
        resolved_api_key = api_key or os.getenv(self.api_key_env_var)
        if not resolved_api_key:
            raise ValueError(
                f"API key not provided and {self.api_key_env_var} environment variable is not set."
            )
        self.api_key = resolved_api_key
        if not api_base:
            raise ValueError("The api_base argument must be provided.")
        self.api_base = api_base
        self.model_name = "baseten-embedding-model"
        self.dimensions = None

        self.client = openai.OpenAI(api_key=self.api_key, base_url=self.api_base)

    @staticmethod
    def name() -> str:
        return "baseten"

    def default_space(self) -> Space:
        return "cosine"

View on GitHub (pinned to aecdd12c8a)

Solutions

Export the env var in every runtime that constructs the function: export CHROMA_BASETEN_API_KEY=... (or BASETEN_API_KEY, which takes precedence if set).
For quick local experiments pass api_key="..." explicitly, accepting the DeprecationWarning that it will not persist.
If you pass a custom api_key_env_var, make sure the exported name matches it character-for-character.

Example fix

# before: ValueError "API key not provided and CHROMA_BASETEN_API_KEY environment variable is not set."
ef = BasetenEmbeddingFunction(api_key=None, api_base="https://app.baseten.co/...")

# after (shell): export CHROMA_BASETEN_API_KEY="bs-..."
# after (python, ephemeral):
ef = BasetenEmbeddingFunction(api_key="bs-...", api_base="https://app.baseten.co/...")

Defensive patterns

Strategy: validation

Validate before calling

import os

API_KEY_ENV = "CHROMA_BASETEN_API_KEY"  # or "BASETEN_API_KEY", which takes precedence
if not (os.getenv(API_KEY_ENV) or os.getenv("BASETEN_API_KEY")):
    raise RuntimeError(f"Set {API_KEY_ENV} before constructing BasetenEmbeddingFunction")

from chromadb.utils.embedding_functions import BasetenEmbeddingFunction
ef = BasetenEmbeddingFunction(api_base=api_base, api_key_env_var=API_KEY_ENV)

Type guard

import os

def has_baseten_credentials() -> bool:
    return bool(os.getenv("BASETEN_API_KEY") or os.getenv("CHROMA_BASETEN_API_KEY"))

Try / catch

try:
    ef = BasetenEmbeddingFunction(api_base=api_base, api_key_env_var="CHROMA_BASETEN_API_KEY")
except ValueError as e:
    if "API key not provided" in str(e):
        raise RuntimeError("Missing Baseten credentials: export CHROMA_BASETEN_API_KEY") from e
    raise

Prevention

Set CHROMA_BASETEN_API_KEY (or BASETEN_API_KEY) in the process environment via your secret manager, not in code.
Load .env files before importing/constructing embedding functions.
Remember api_key= is ephemeral (not persisted) — env vars are the durable mechanism.

When it happens

Trigger: BasetenEmbeddingFunction(api_key=None, api_base=...) — the exact call build_from_config makes — while neither BASETEN_API_KEY nor CHROMA_BASETEN_API_KEY (or your custom api_key_env_var) is set in the process environment.

Common situations: Server/worker containers missing the secret; .env file not loaded before chromadb imports; typo'd variable name; moving a persisted collection config to a new machine (api_key is deliberately not persisted, only the env-var name is).

Related errors

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