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

OpenAIEmbeddingFunction.validate_config_update raises ValueError whenever the proposed configuration update contains the key "model_name". Chroma calls validate_config_update (from chromadb/api/collection_configuration.py) when you change a collection's embedding function; because OpenAI embeddings cannot be re-computed under a different model without invalidating all existing vectors, the model is treated as immutable after collection creation. Any update payload that includes model_name — even one with the same value — is rejected.

Source

Thrown at chromadb/utils/embedding_functions/openai_embedding_function.py:195

    def get_config(self) -> Dict[str, Any]:
        return {
            "api_key_env_var": self.api_key_env_var,
            "model_name": self.model_name,
            "organization_id": self.organization_id,
            "api_base": self.api_base,
            "api_type": self.api_type,
            "api_version": self.api_version,
            "deployment_id": self.deployment_id,
            "default_headers": self.default_headers,
            "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, "openai")

View on GitHub (pinned to aecdd12c8a)

Solutions

Create a new collection with the desired embedding function and re-embed your documents (embeddings from different models are not comparable, so in-place migration is impossible anyway).
If you only meant to change non-model settings (e.g. api_base, organization_id), build the update so model_name is excluded from the new config payload.
For a model upgrade, plan a backfill: create collection_v2 with the new OpenAIEmbeddingFunction, re-embed source documents, then switch reads/writes and drop the old collection.
Check chromadb release notes — newer versions expose collection.modify on specific EF fields; model_name was and stays non-updatable for OpenAI.

Example fix

// before
collection.modify(
    embedding_function=OpenAIEmbeddingFunction(model_name="text-embedding-3-small")
)  # ValueError: The model name cannot be changed after the embedding function has been initialized.

# after
new_col = client.create_collection(
    "docs_v2",
    embedding_function=OpenAIEmbeddingFunction(
        model_name="text-embedding-3-small", dimensions=256
    ),
)
new_col.add(ids=old_ids, documents=old_docs)  # re-embed into the new collection

Defensive patterns

Strategy: validation

Validate before calling

def assert_no_model_name_in_update(new_config: dict) -> None:
    if "model_name" in new_config:
        raise RuntimeError(
            "model_name is immutable; create a new collection and re-embed instead of calling modify"
        )

# strip the key before any update payload reaches modify()
assert_no_model_name_in_update(planned_update)

Type guard

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

Try / catch

try:
    collection.modify(embedding_function=new_ef)
except ValueError as e:
    if "model name cannot be changed" in str(e).lower():
        # fall back to create-new-collection + re-embed migration
        ...
    raise

Prevention

Treat the embedding model as part of a collection's identity: record it in collection metadata at creation.
Never round-trip get_config() into modify(); build update payloads with explicit allowed keys only.
Plan model upgrades as re-index migrations (new collection, re-embed, swap alias), not in-place edits.
Write an integration test that asserts modify() with a changed EF raises, so the constraint is documented in code.

When it happens

Trigger: Calling collection.modify(...) (or the internal EF update path) with a new OpenAIEmbeddingFunction whose get_config() payload carries model_name — which is always the case, since get_config() includes it. So attempting to swap the embedding function on an existing collection, e.g. to change dimensions or model, hits this error; constructing a fresh collection does not.

Common situations: Wanting to upgrade text-embedding-ada-002 to text-embedding-3-small on an existing collection; trying to add/change the dimensions parameter by replacing the embedding function via modify; writing config-management code that round-trips get_config() into an update payload and accidentally includes model_name.

Related errors

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