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

Like other provider functions, CohereEmbeddingFunction forbids config updates that would change model_name: embeddings from different Cohere models (e.g. embed-english-v3.0 vs embed-multilingual-v3.0) are not comparable, so patching the model would silently corrupt similarity search. validate_config_update raises whenever 'model_name' appears in new_config, even with an identical value.

Source

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

    @staticmethod
    def build_from_config(config: Dict[str, Any]) -> "EmbeddingFunction[Embeddable]":
        api_key_env_var = config.get("api_key_env_var")
        model_name = config.get("model_name")
        if api_key_env_var is None or model_name is None:
            assert False, "This code should not be reached"

        return CohereEmbeddingFunction(
            api_key_env_var=api_key_env_var, model_name=model_name
        )

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

    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."
            )

    @staticmethod
    def validate_config(config: Dict[str, Any]) -> None:
        """
        Validate the configuration using the JSON schema.

        Args:
            config: Configuration to validate

        Raises:
            ValidationError: If the configuration does not match the schema
        """
        validate_config_schema(config, "cohere")

View on GitHub (pinned to aecdd12c8a)

Solutions

Remove 'model_name' from the update dict; send only the keys that actually change (e.g. {'api_key_env_var': ...}).
To switch models, create a new collection with a new CohereEmbeddingFunction(model_name=...) and re-embed.
Build patch payloads explicitly rather than from get_config() round-trips.

Example fix

# before
cfg = ef.get_config()  # {'api_key_env_var': ..., 'model_name': 'embed-english-v3.0'}
cfg['api_key_env_var'] = 'PROD_COHERE_KEY'
ef.validate_config_update(old, cfg)  # ValueError

# after
patch = {'api_key_env_var': 'PROD_COHERE_KEY'}
ef.validate_config_update(old, patch)

Defensive patterns

Strategy: validation

Validate before calling

patch = {k: v for k, v in new_cfg.items() if k != 'model_name'}
ef.validate_config_update(old_cfg, patch)

Try / catch

try:
    ef.validate_config_update(old_cfg, new_cfg)
except ValueError as e:
    if 'model name cannot be changed' in str(e):
        new_cfg.pop('model_name', None)
        ef.validate_config_update(old_cfg, new_cfg)
    else:
        raise

Prevention

Patch configs with only changed keys; model_name is immutable by design.
Model swaps: new collection, new embedding function, re-embed.
Wrap config updates in a helper that strips immutable fields.

When it happens

Trigger: Calling the config-update path with a dict that includes 'model_name' - typically because get_config() output (which contains api_key_env_var and model_name) was echoed back as the update payload with one other field edited.

Common situations: Rotating the API key env var via config update while round-tripping the whole config; automation that does read-modify-write on embedding function configs.

Related errors

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