{"record":{"id":"a39e86d637c21b2d","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-the-embeddi-a39e86","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/cohere_embedding_function.py","lineNumber":167,"sourceCode":"    @staticmethod\n    def build_from_config(config: Dict[str, Any]) -> \"EmbeddingFunction[Embeddable]\":\n        api_key_env_var = config.get(\"api_key_env_var\")\n        model_name = config.get(\"model_name\")\n        if api_key_env_var is None or model_name is None:\n            assert False, \"This code should not be reached\"\n\n        return CohereEmbeddingFunction(\n            api_key_env_var=api_key_env_var, model_name=model_name\n        )\n\n    def get_config(self) -> Dict[str, Any]:\n        return {\"api_key_env_var\": self.api_key_env_var, \"model_name\": self.model_name}\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, \"cohere\")\n","sourceCodeStart":149,"sourceCodeEnd":183,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/cohere_embedding_function.py#L149-L183","documentation":"Like other provider functions, CohereEmbeddingFunction forbids config updates that would change model_name: embeddings from different Cohere models (e.g. embed-english-v3.0 vs embed-multilingual-v3.0) are not comparable, so patching the model would silently corrupt similarity search. validate_config_update raises whenever 'model_name' appears in new_config, even with an identical value.","triggerScenarios":"Calling the config-update path with a dict that includes 'model_name' - typically because get_config() output (which contains api_key_env_var and model_name) was echoed back as the update payload with one other field edited.","commonSituations":"Rotating the API key env var via config update while round-tripping the whole config; automation that does read-modify-write on embedding function configs.","solutions":["Remove 'model_name' from the update dict; send only the keys that actually change (e.g. {'api_key_env_var': ...}).","To switch models, create a new collection with a new CohereEmbeddingFunction(model_name=...) and re-embed.","Build patch payloads explicitly rather than from get_config() round-trips."],"exampleFix":"# before\ncfg = ef.get_config()  # {'api_key_env_var': ..., 'model_name': 'embed-english-v3.0'}\ncfg['api_key_env_var'] = 'PROD_COHERE_KEY'\nef.validate_config_update(old, cfg)  # ValueError\n\n# after\npatch = {'api_key_env_var': 'PROD_COHERE_KEY'}\nef.validate_config_update(old, patch)","handlingStrategy":"validation","validationCode":"patch = {k: v for k, v in new_cfg.items() if k != 'model_name'}\nef.validate_config_update(old_cfg, patch)","typeGuard":null,"tryCatchPattern":"try:\n    ef.validate_config_update(old_cfg, new_cfg)\nexcept ValueError as e:\n    if 'model name cannot be changed' in str(e):\n        new_cfg.pop('model_name', None)\n        ef.validate_config_update(old_cfg, new_cfg)\n    else:\n        raise","preventionTips":["Patch configs with only changed keys; model_name is immutable by design.","Model swaps: new collection, new embedding function, re-embed.","Wrap config updates in a helper that strips immutable fields."],"tags":["chroma","cohere","config-update","embedding-function","immutable-field"],"backgroundTag":"immutable-config-field","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}