{"record":{"id":"735499ef0b44428a","repo":"chroma-core/chroma","slug":"the-checkpoint-cannot-be-changed-after-the-embeddi","errorCode":null,"errorMessage":"The checkpoint cannot be changed after the embedding function has been initialized.","messagePattern":"The checkpoint 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":172,"sourceCode":"            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        \"\"\"\n        validate_config_schema(config, \"open_clip\")\n","sourceCodeStart":154,"sourceCodeEnd":188,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/open_clip_embedding_function.py#L154-L188","documentation":"The second guard in OpenCLIPEmbeddingFunction.validate_config_update raises ValueError when new_config contains \"checkpoint\". The checkpoint is the pretrained weight set for the open_clip model (e.g. laion2b_s34b_b79k); swapping weights changes what the vectors mean even when the architecture (model_name) stays the same, so embeddings in an existing collection would silently become incomparable. Model and checkpoint must be chosen together at creation time.","triggerScenarios":"Updating EF config with {\"checkpoint\": \"laion2b_s32b_b79k\"} on a collection created with laion2b_s34b_b79k; trying to hot-swap to fine-tuned weights; config tooling that re-applies a full get_config() dict where checkpoint was edited.","commonSituations":"Adopting newly released open_clip checkpoints on existing collections; using organization-fine-tuned weights in a config-managed deployment; diffs of persisted config JSON applied automatically by GitOps.","solutions":["Rebuild: new collection + new OpenCLIPEmbeddingFunction with the desired checkpoint + re-embed images","Keep model_name and checkpoint as an atomic pair in collection naming/metadata (e.g. collection \"imgs_vitb32_laion2b_s34b\") so swaps are explicit migrations","If the update was accidental, drop the \"checkpoint\" key from the payload"],"exampleFix":"// before\nnew_cfg = fn.get_config(); new_cfg[\"checkpoint\"] = \"laion2b_s32b_b82k\"\nfn.validate_config_update(fn.get_config(), new_cfg)  # ValueError\n\n// after\nfn2 = OpenCLIPEmbeddingFunction(model_name=\"ViT-B-32\", checkpoint=\"laion2b_s32b_b82k\")\ncol2 = client.create_collection(\"imgs_vitb32_s32b_b82k\", embedding_function=fn2)\n# migrate images from the old collection","handlingStrategy":"validation","validationCode":"def assert_checkpoint_update_safe(new_config: dict) -> None:\n    if \"checkpoint\" in new_config:\n        raise ValueError(\"checkpoint is immutable; rebuild the collection with new weights\")","typeGuard":null,"tryCatchPattern":"try:\n    fn.validate_config_update(old_cfg, new_cfg)\nexcept ValueError as e:\n    if \"checkpoint cannot be changed\" in str(e):\n        new_cfg.pop(\"checkpoint\", None)  # or trigger re-embed migration\n    else:\n        raise","preventionTips":["Always change model_name and checkpoint together, via a new collection","Don't auto-apply full config dicts from external sources without key filtering","Version embeddings by checkpoint in metadata so old/new vectors are never mixed"],"tags":["openclip","embedding-function","immutable-config","checkpoint","chroma"],"backgroundTag":"immutable-config-update","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}