{"record":{"id":"c772711febe2b71b","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-the-embeddi-c77271","errorCode":null,"errorMessage":"The model name cannot be changed after the embedding function has been initialized.","messagePattern":"The model name cannot be changed after the embedding function has been initialized\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/openai_embedding_function.py","lineNumber":195,"sourceCode":"\n    def get_config(self) -> Dict[str, Any]:\n        return {\n            \"api_key_env_var\": self.api_key_env_var,\n            \"model_name\": self.model_name,\n            \"organization_id\": self.organization_id,\n            \"api_base\": self.api_base,\n            \"api_type\": self.api_type,\n            \"api_version\": self.api_version,\n            \"deployment_id\": self.deployment_id,\n            \"default_headers\": self.default_headers,\n            \"dimensions\": self.dimensions,\n        }\n\n    def validate_config_update(\n        self, old_config: Dict[str, Any], new_config: Dict[str, Any]\n    ) -> None:\n        if \"model_name\" in new_config:\n            raise ValueError(\n                \"The model name cannot be changed after the embedding function has been initialized.\"\n            )\n\n    @staticmethod\n    def validate_config(config: Dict[str, Any]) -> None:\n        \"\"\"\n        Validate the configuration using the JSON schema.\n\n        Args:\n            config: Configuration to validate\n\n        Raises:\n            ValidationError: If the configuration does not match the schema\n        \"\"\"\n        validate_config_schema(config, \"openai\")\n","sourceCodeStart":177,"sourceCodeEnd":211,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/openai_embedding_function.py#L177-L211","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ncollection.modify(\n    embedding_function=OpenAIEmbeddingFunction(model_name=\"text-embedding-3-small\")\n)  # ValueError: The model name cannot be changed after the embedding function has been initialized.\n\n# after\nnew_col = client.create_collection(\n    \"docs_v2\",\n    embedding_function=OpenAIEmbeddingFunction(\n        model_name=\"text-embedding-3-small\", dimensions=256\n    ),\n)\nnew_col.add(ids=old_ids, documents=old_docs)  # re-embed into the new collection","handlingStrategy":"validation","validationCode":"def assert_no_model_name_in_update(new_config: dict) -> None:\n    if \"model_name\" in new_config:\n        raise RuntimeError(\n            \"model_name is immutable; create a new collection and re-embed instead of calling modify\"\n        )\n\n# strip the key before any update payload reaches modify()\nassert_no_model_name_in_update(planned_update)","typeGuard":"def is_safe_ef_update(new_config: dict) -> bool:\n    return \"model_name\" not in new_config","tryCatchPattern":"try:\n    collection.modify(embedding_function=new_ef)\nexcept ValueError as e:\n    if \"model name cannot be changed\" in str(e).lower():\n        # fall back to create-new-collection + re-embed migration\n        ...\n    raise","preventionTips":["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."],"tags":["openai","embedding","model-name","immutable","collection-modify","chroma"],"backgroundTag":"immutable-config-update","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}