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

Chroma embedding functions support config-based reconfiguration, but JinaEmbeddingFunction.validate_config_update rejects any update payload that contains the key 'model_name', raising this ValueError. Changing the model would silently change the vector space of already-stored embeddings, corrupting similarity search, so the field is immutable by design. All other config keys (task, late_chunking, truncate, dimensions, embedding_type, normalized, query_config) may be updated.

Source

Thrown at chromadb/utils/embedding_functions/jina_embedding_function.py:268

    def get_config(self) -> Dict[str, Any]:
        return {
            "api_key_env_var": self.api_key_env_var,
            "model_name": self.model_name,
            "task": self.task,
            "late_chunking": self.late_chunking,
            "truncate": self.truncate,
            "dimensions": self.dimensions,
            "embedding_type": self.embedding_type,
            "normalized": self.normalized,
            "query_config": self.query_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."
            )

    @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, "jina")

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Create a new embedding function / new collection for the new model and re-index, rather than updating in place
2. Strip immutable keys before updating: new_config.pop('model_name', None)
3. Diff old vs new config and only send genuinely changed, mutable keys

Example fix

# before
new_config = ef.get_config()
new_config["model_name"] = "jina-clip-v2"
ef.validate_config_update(ef.get_config(), new_config)  # ValueError

# after
new_config = {k: v for k, v in ef.get_config().items() if k != "model_name"}
new_config["dimensions"] = 512
ef.validate_config_update(ef.get_config(), new_config)  # ok

IMMUTABLE = {"model_name"}

def safe_update(ef, new_config: dict) -> dict:
    illegal = IMMUTABLE & new_config.keys()
    if illegal:
        raise ValueError(
            f"cannot update immutable keys {illegal}; create a new EF/collection instead"
        )
    ef.validate_config_update(ef.get_config(), new_config)
    return new_config

try:
    ef.validate_config_update(old_config, new_config)
except ValueError as e:
    if "cannot be changed" in str(e):
        new_config = {k: v for k, v in new_config.items() if k != "model_name"}
        ef.validate_config_update(old_config, new_config)
    else:
        raise

When it happens

Trigger: Calling the EF/collection config-update API with {'model_name': 'jina-clip-v2', ...}; deserializing and re-applying a full get_config() dict that round-trips model_name back into an update; UI/tooling that PUTs the entire config instead of only changed keys.

Common situations: Migrating to a new Jina model by attempting an in-place config edit; config-sync tooling that sends whole config objects; copy-pasting get_config() output into an update call during debugging.

Related errors

• The model cannot be changed after the embedding function has
• The model name cannot be changed after the embedding functio
• CohereEmbeddingFunction model_name cannot be changed after i
• DefaultEmbeddingFunction model cannot be changed after initi
• Jina AI API key is required. Please provide it in the constr

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