chroma-core/chroma · error · ValueError

api_key_env_var must be provided in config

Error message

api_key_env_var must be provided in config

What it means

build_from_config raises ValueError when config.get("api_key_env_var") is falsy (missing, None, or empty string). The env var name is required to resolve credentials when the function is reconstructed, even though the key itself is deliberately not persisted (only the variable name is).

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py:155

                normalize_sparse_vector(indices=indices, values=values, labels=labels)
            )

        return normalized_vectors

    @staticmethod
    def name() -> str:
        return "chroma-cloud-splade"

    @staticmethod
    def build_from_config(
        config: Dict[str, Any]
    ) -> "SparseEmbeddingFunction[Documents]":
        api_key_env_var = config.get("api_key_env_var")
        model = config.get("model")
        if model is None:
            raise ValueError("model must be provided in config")
        if not api_key_env_var:
            raise ValueError("api_key_env_var must be provided in config")
        return ChromaCloudSpladeEmbeddingFunction(
            api_key_env_var=api_key_env_var,
            model=ChromaCloudSpladeEmbeddingModel(model),
            include_tokens=config.get("include_tokens", False),
        )

    def get_config(self) -> Dict[str, Any]:
        return {
            "api_key_env_var": self.api_key_env_var,
            "model": self.model.value,
            "include_tokens": self.include_tokens,
        }

    def validate_config_update(
        self, old_config: Dict[str, Any], new_config: Dict[str, Any]
    ) -> None:
        immutable_keys = {"include_tokens", "model"}
        for key in immutable_keys:

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Add "api_key_env_var": "CHROMA_API_KEY" (or your custom variable name) to the config.
2. Round-trip configs via get_config() so all required keys survive.
3. Ensure the named variable is actually exported at rebuild time, otherwise the constructor will next fail with the API-key-not-found error.

Example fix

# before
ef = ChromaCloudSpladeEmbeddingFunction.build_from_config(
    {"model": "prithivida/Splade_PP_en_v1"}  # ValueError: api_key_env_var must be provided
)

# after
ef = ChromaCloudSpladeEmbeddingFunction.build_from_config({
    "model": "prithivida/Splade_PP_en_v1",
    "api_key_env_var": "CHROMA_API_KEY",
})

if not config.get("api_key_env_var"):
    config["api_key_env_var"] = "CHROMA_API_KEY"  # or fail loudly:
    # raise ValueError("config['api_key_env_var'] is required")
ef = ChromaCloudSpladeEmbeddingFunction.build_from_config(config)

def is_buildable_splade_config(config: dict) -> bool:
    return config.get("model") in {m.value for m in ChromaCloudSpladeEmbeddingModel} and bool(config.get("api_key_env_var"))

When it happens

Trigger: Calling ChromaCloudSpladeEmbeddingFunction.build_from_config(config) where config has no 'api_key_env_var' key or it is set to "" — e.g. a config dict assembled by hand that only includes 'model'.

Common situations: Manually constructed configs that omit credential-related fields; older persisted configs predating api_key_env_var serialization; copy-pasted examples trimmed for brevity.

Related errors

• model must be provided in config
• API key not found in environment variable {self.api_key_env_
• Updating '{key}' is not supported for chroma-cloud-splade
• Could not build embedding function {ef_config['name']} from
• API key not found in environment variable {api_key_env_var}

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