chroma-core/chroma · error · ValueError

The model name cannot be changed after the embedding functio

Error message

The model name cannot be changed after the embedding function has been initialized.

What it means

GoogleGeminiEmbeddingFunction.validate_config_update rejects any update payload whose dict contains a 'model_name' key. Switching the embedding model after a collection exists would make new vectors semantically incompatible with stored ones (different vector space, possibly different dimension), so the field is immutable. Note that get_config() output always includes model_name - passing a full config as the update payload will always trip this.

Source

Thrown at chromadb/utils/embedding_functions/google_embedding_function.py:175

    def get_config(self) -> Dict[str, Any]:
        config: Dict[str, Any] = {
            "model_name": self.model_name,
            "api_key_env_var": self.api_key_env_var,
            "vertexai": self.vertexai,
            "project": self.project,
            "location": self.location,
        }
        if self.task_type is not None:
            config["task_type"] = self.task_type
        if self.dimension is not None:
            config["dimension"] = self.dimension
        return config

    def validate_config_update(
        self, old_config: Dict[str, Any], new_config: Dict[str, Any]
    ) -> None:
        if "model_name" in new_config:
            raise ValueError(
                "The model name cannot be changed after the embedding function has been initialized."
            )
        if "dimension" in new_config:
            raise ValueError(
                "The dimension cannot be changed after the embedding function has been initialized."
            )
        if "vertexai" in new_config:
            raise ValueError(
                "The vertexai cannot be changed after the embedding function has been initialized."
            )
        if "project" in new_config:
            raise ValueError(
                "The project cannot be changed after the embedding function has been initialized."
            )
        if "location" in new_config:
            raise ValueError(
                "The location cannot be changed after the embedding function has been initialized."
            )

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Create a new collection with the new model and re-embed your documents - model changes cannot be done in place
2. When updating mutable settings (api_key_env_var, task_type), pass a dict containing only those keys, never the full config
3. Strip immutable keys (model_name, dimension, vertexai, project, location) from any payload before calling modify/validate_config_update

Example fix

# before
new_ef = GoogleGeminiEmbeddingFunction(model_name="gemini-embedding-001")
collection.modify(embedding_function=new_ef)  # config contains model_name -> ValueError

# after - update only mutable keys, or migrate to a new collection
new_ef = GoogleGeminiEmbeddingFunction(
    model_name=old_model_name,           # unchanged
    api_key_env_var="GOOGLE_API_KEY",    # the actual change
    task_type="RETRIEVAL_QUERY",
)
collection.modify(embedding_function=new_ef)

IMMUTABLE = {"model_name", "dimension", "vertexai", "project", "location"}

update = {k: v for k, v in desired_config.items() if k not in IMMUTABLE}
assert "model_name" not in update
ef.validate_config_update(old_config, update)

from typing import Any, TypeGuard

MUTABLE_GEMINI_KEYS = {"api_key_env_var", "task_type"}

def is_mutable_update(cfg: Any) -> TypeGuard[dict]:
    return isinstance(cfg, dict) and set(cfg) <= MUTABLE_GEMINI_KEYS

When it happens

Trigger: collection.modify(embedding_function=other_ef) where the new function's config contains model_name (i.e. essentially every rebuild); calling validate_config_update(old, new) with new built from ef.get_config(); programmatic config updates that diff against a complete config instead of only changed keys.

Common situations: Attempting to swap 'gemini-embedding-001' for a newer model on an existing collection; using a copied get_config() dict as the modification payload; upgrade scripts that rewrite the whole embedding config.

Related errors

• The dimension cannot be changed after the embedding function
• The vertexai cannot be changed after the embedding function
• Updating '{key}' is not supported for {NAME}
• The google-genai python package is not installed. Please ins
• Vertex AI and API key are mutually exclusive in the client i

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