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

Embedding-function configs are patchable except for fields that would silently change the vector space. For CloudflareWorkersAIEmbeddingFunction, model_name is such a field: validate_config_update rejects any new_config that contains 'model_name', even if the value is unchanged. Embeddings from two different models are not comparable, so a model swap requires a new collection.

Source

Thrown at chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py:144

            api_key_env_var=api_key_env_var,
            model_name=model_name,
            account_id=account_id,
            gateway_id=gateway_id,
        )

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

    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, "cloudflare_workers_ai")

View on GitHub (pinned to aecdd12c8a)

Solutions

Send a minimal patch dict containing only the keys you actually change, with 'model_name' removed.
If you need a different model, create a new collection with a fresh embedding function and re-embed your documents.
Construct the update payload explicitly (e.g. {'api_key_env_var': ...}) instead of copying get_config() output.

Example fix

# before
cfg = ef.get_config()
cfg['api_key_env_var'] = 'CLOUDFLARE_API_KEY_PROD'
ef.validate_config_update(old, cfg)  # ValueError: model_name cannot change

# after
patch = {'api_key_env_var': 'CLOUDFLARE_API_KEY_PROD'}  # changed keys only
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)  # retry with immutable fields stripped
        ef.validate_config_update(old_cfg, new_cfg)
    else:
        raise

Prevention

Send minimal diff dicts to config updates; never echo full get_config() payloads.
Treat model_name as immutable: a model change means a new collection and re-embedding.
Centralize config-update building in one helper that strips known-immutable keys.

When it happens

Trigger: A config update that calls validate_config_update(old, new) with 'model_name' present in new - most commonly because the full get_config() dict was echoed back with one other field (api_key_env_var, account_id, gateway_id) edited.

Common situations: Round-tripping configs: users fetch get_config(), mutate a key, and pass the whole dict to the update API, forgetting that model_name rides along.

Related errors

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