{"record":{"id":"5e06fc82b8d782d5","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-the-embeddi-5e06fc","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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/google_embedding_function.py","lineNumber":175,"sourceCode":"    def get_config(self) -> Dict[str, Any]:\n        config: Dict[str, Any] = {\n            \"model_name\": self.model_name,\n            \"api_key_env_var\": self.api_key_env_var,\n            \"vertexai\": self.vertexai,\n            \"project\": self.project,\n            \"location\": self.location,\n        }\n        if self.task_type is not None:\n            config[\"task_type\"] = self.task_type\n        if self.dimension is not None:\n            config[\"dimension\"] = self.dimension\n        return config\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        if \"dimension\" in new_config:\n            raise ValueError(\n                \"The dimension cannot be changed after the embedding function has been initialized.\"\n            )\n        if \"vertexai\" in new_config:\n            raise ValueError(\n                \"The vertexai cannot be changed after the embedding function has been initialized.\"\n            )\n        if \"project\" in new_config:\n            raise ValueError(\n                \"The project cannot be changed after the embedding function has been initialized.\"\n            )\n        if \"location\" in new_config:\n            raise ValueError(\n                \"The location cannot be changed after the embedding function has been initialized.\"\n            )","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/google_embedding_function.py#L157-L193","documentation":"GoogleGeminiEmbeddingFunction.validate_config_update rejects any update payload whose dict contains a 'model_name' key. Switching the embedding model after a collection exists would make new vectors semantically incompatible with stored ones (different vector space, possibly different dimension), so the field is immutable. Note that get_config() output always includes model_name - passing a full config as the update payload will always trip this.","triggerScenarios":"collection.modify(embedding_function=other_ef) where the new function's config contains model_name (i.e. essentially every rebuild); calling validate_config_update(old, new) with new built from ef.get_config(); programmatic config updates that diff against a complete config instead of only changed keys.","commonSituations":"Attempting to swap 'gemini-embedding-001' for a newer model on an existing collection; using a copied get_config() dict as the modification payload; upgrade scripts that rewrite the whole embedding config.","solutions":["Create a new collection with the new model and re-embed your documents - model changes cannot be done in place","When updating mutable settings (api_key_env_var, task_type), pass a dict containing only those keys, never the full config","Strip immutable keys (model_name, dimension, vertexai, project, location) from any payload before calling modify/validate_config_update"],"exampleFix":"# before\nnew_ef = GoogleGeminiEmbeddingFunction(model_name=\"gemini-embedding-001\")\ncollection.modify(embedding_function=new_ef)  # config contains model_name -> ValueError\n\n# after - update only mutable keys, or migrate to a new collection\nnew_ef = GoogleGeminiEmbeddingFunction(\n    model_name=old_model_name,           # unchanged\n    api_key_env_var=\"GOOGLE_API_KEY\",    # the actual change\n    task_type=\"RETRIEVAL_QUERY\",\n)\ncollection.modify(embedding_function=new_ef)","handlingStrategy":"validation","validationCode":"IMMUTABLE = {\"model_name\", \"dimension\", \"vertexai\", \"project\", \"location\"}\n\nupdate = {k: v for k, v in desired_config.items() if k not in IMMUTABLE}\nassert \"model_name\" not in update\nef.validate_config_update(old_config, update)","typeGuard":"from typing import Any, TypeGuard\n\nMUTABLE_GEMINI_KEYS = {\"api_key_env_var\", \"task_type\"}\n\ndef is_mutable_update(cfg: Any) -> TypeGuard[dict]:\n    return isinstance(cfg, dict) and set(cfg) <= MUTABLE_GEMINI_KEYS","tryCatchPattern":null,"preventionTips":["Never pass a full get_config() dict as an update payload - it always contains model_name","Treat model changes as migration: new collection, re-embed, switch read path","Diff old vs new configs and strip immutable keys programmatically before modify()"],"tags":["immutable-config","collection-modify","gemini","chroma"],"backgroundTag":"immutable-config-field","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}