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

MorphEmbeddingFunction.validate_config_update rejects any update config containing 'model_name', raising this ValueError. The embedding model defines the output vector space, so changing it after data has been embedded would corrupt similarity search over existing records — hence immutable. Mutable keys include api_key_env_var, api_base, and encoding_format.

Source

Thrown at chromadb/utils/embedding_functions/morph_embedding_function.py:132

            api_key_env_var=api_key_env_var,
            model_name=model_name,
            api_base=api_base if api_base is not None else "https://api.morphllm.com/v1",
            encoding_format=encoding_format if encoding_format is not None else "float",
        )

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

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

View on GitHub (pinned to aecdd12c8a)

Solutions

Spin up a new EF/collection with the new model_name and re-embed the data
Remove the key before update: new_config.pop('model_name', None)
Only send changed, mutable keys in update payloads

Example fix

# before
new_cfg = ef.get_config()          # includes "model_name"
new_cfg["model_name"] = "morph-embedding-v3"
ef.validate_config_update(ef.get_config(), new_cfg)  # ValueError

# after
new_cfg = {"encoding_format": "base64", "api_base": "https://api.morphllm.com/v1"}
ef.validate_config_update(ef.get_config(), new_cfg)  # ok

Defensive patterns

Strategy: validation

Validate before calling

def safe_morph_update(ef, new_config: dict) -> dict:
    if "model_name" in new_config:
        raise ValueError(
            "model_name is immutable; create a new collection and re-embed"
        )
    ef.validate_config_update(ef.get_config(), new_config)
    return new_config

Try / catch

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

Prevention

Send only changed mutable keys (api_base, encoding_format, api_key_env_var) in updates
Handle model upgrades as re-index migrations with a fresh collection
Strip immutable keys in a shared update helper instead of relying on API failures

When it happens

Trigger: Config-update calls that include model_name (e.g. attempting to move from morph-embedding-v2 to a newer model in place); re-submitting a full get_config() dict as the update payload; automation that diffs whole configs and PUTs everything.

Common situations: Model-version upgrades treated as config edits; config round-tripping through admin UIs; debugging sessions pasting get_config() output into update calls.

Related errors

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