{"record":{"id":"431f89a5d6d475f8","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-the-embeddi-431f89","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/open_clip_embedding_function.py","lineNumber":168,"sourceCode":"        if model_name is None or checkpoint is None or device is None:\n            assert False, \"This code should not be reached\"\n\n        return OpenCLIPEmbeddingFunction(\n            model_name=model_name, checkpoint=checkpoint, device=device\n        )\n\n    def get_config(self) -> Dict[str, Any]:\n        return {\n            \"model_name\": self.model_name,\n            \"checkpoint\": self.checkpoint,\n            \"device\": self.device,\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        if \"checkpoint\" in new_config:\n            raise ValueError(\n                \"The checkpoint 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        \"\"\"","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/open_clip_embedding_function.py#L150-L186","documentation":"OpenCLIPEmbeddingFunction.get_config() persists {model_name, checkpoint, device} and validate_config_update() raises ValueError if new_config contains \"model_name\". The model architecture determines the embedding dimension (ViT-B-32 -> 512-dim), so changing it after a collection was populated would store vectors in an incompatible space; Chroma's config protocol therefore treats model_name as create-time-only. Note \"checkpoint\" is rejected too, while \"device\" is not checked here.","triggerScenarios":"Pushing an EF config update containing {\"model_name\": \"ViT-L-14\"} via the flow that calls validate_config_update(old_config, new_config); hand-editing persisted EF config JSON to a different model; migration scripts that round-trip get_config(), mutate model_name, and reapply.","commonSituations":"Upgrading from ViT-B-32 to a better model on an existing image collection; shared config templates applied to many collections with different models; misunderstanding which fields are mutable (only device survives this check).","solutions":["Create a new collection with the new model_name (and matching checkpoint) and re-embed all images","If you only meant to move computation, update \"device\" (e.g. cpu -> cuda) — that key is allowed","Remove \"model_name\" (and \"checkpoint\") from the update payload"],"exampleFix":"// before\nnew_cfg = fn.get_config(); new_cfg[\"model_name\"] = \"ViT-L-14\"\nfn.validate_config_update(fn.get_config(), new_cfg)  # ValueError\n\n// after\nfn_l14 = OpenCLIPEmbeddingFunction(model_name=\"ViT-L-14\", checkpoint=\"laion2b_s32b_b82k\")\ncol2 = client.create_collection(\"images_vitl14\", embedding_function=fn_l14)\n# re-add images; new vectors are 768-dim","handlingStrategy":"validation","validationCode":"IMMUTABLE = {\"model_name\", \"checkpoint\"}\ndef assert_openclip_update_safe(new_config: dict) -> None:\n    blocked = IMMUTABLE & set(new_config)\n    if blocked:\n        raise ValueError(f\"immutable keys {blocked}: create a new collection to change model/checkpoint\")","typeGuard":null,"tryCatchPattern":"try:\n    fn.validate_config_update(old_cfg, new_cfg)\nexcept ValueError as e:\n    if \"model name cannot be changed\" in str(e):\n        # route to create-new-collection + re-embed migration\n        ...\n    raise","preventionTips":["Only \"device\" is updatable for OpenCLIP EFs; treat model_name/checkpoint as creation-time inputs","Encode model+checkpoint in collection names or metadata to make migrations explicit","Audit config-update payloads for forbidden keys before applying"],"tags":["openclip","embedding-function","immutable-config","config-update","chroma"],"backgroundTag":"immutable-config-update","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}