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

PerplexityEmbeddingFunction.validate_config_update raises ValueError if the incoming configuration update dict contains "model_name". Chroma invokes this hook (chromadb/api/collection_configuration.py) when a collection's embedding function is being modified; the embedding model is immutable because switching it would make all previously stored Perplexity vectors incomparable with new ones. The check is a plain key-presence test, so even an unchanged model_name value in the payload is rejected.

Source

Thrown at chromadb/utils/embedding_functions/perplexity_embedding_function.py:121

        return PerplexityEmbeddingFunction(
            api_key_env_var=api_key_env_var,
            model_name=model_name,
            dimensions=dimensions,
        )

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

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

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Create a new collection with the desired PerplexityEmbeddingFunction(model_name=..., dimensions=...) and re-index your documents into it.
2. If you intended to keep the model and only tweak other fields, submit an update config that excludes the model_name key.
3. Automate the migration: read old collection data, add to the new collection, verify counts, then delete the old one.
4. Pin the model choice at project start and record it alongside collection metadata so future upgrades are planned as re-indexes.

Example fix

// before
collection.modify(
    embedding_function=PerplexityEmbeddingFunction(model_name="pplx-embed-v1-0.6b", dimensions=512)
)  # ValueError: The model name cannot be changed after the embedding function has been initialized.

# after
new_col = client.create_collection(
    "docs_pplx_v2",
    embedding_function=PerplexityEmbeddingFunction(model_name="pplx-embed-v1-0.6b", dimensions=512),
)
for batch in existing_col.get(limit=-1)["documents"]:
    new_col.add(...)  # re-embed with the new function

def strip_immutable_keys(new_config: dict) -> dict:
    return {k: v for k, v in new_config.items() if k != "model_name"}

# only pass mutable fields to the update path
safe_update = strip_immutable_keys(desired_config)

def is_mutable_ef_update(new_config: dict) -> bool:
    return "model_name" not in new_config

try:
    collection.modify(embedding_function=new_pplx_ef)
except ValueError as e:
    if "model name cannot be changed" in str(e).lower():
        raise RuntimeError("Re-create the collection with the new model and re-embed") from e
    raise

When it happens

Trigger: Calling collection.modify(...) with a replacement PerplexityEmbeddingFunction — its get_config() always returns model_name, so the update payload carries the key and the call raises. Only updates that omit model_name entirely can proceed.

Common situations: Trying to move from the default pplx-embed model to a newer release on an existing collection; attempting to change the Matryoshka dimensions by swapping the EF via modify; generic config tooling that diffs get_config() against a desired config and submits the whole dict.

Related errors

• The model name cannot be changed after the embedding functio
• The perplexityai python package is not installed. Please ins
• The {self.api_key_env_var} environment variable is not set.
• The model name cannot be changed after the embedding functio
• The {self.api_key_env_var} environment variable is not set.

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