chroma-core/chroma · error · ValueError

The checkpoint cannot be changed after the embedding functio

Error message

The checkpoint cannot be changed after the embedding function has been initialized.

What it means

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.

Source

Thrown at chromadb/utils/embedding_functions/open_clip_embedding_function.py:172

            model_name=model_name, checkpoint=checkpoint, device=device
        )

    def get_config(self) -> Dict[str, Any]:
        return {
            "model_name": self.model_name,
            "checkpoint": self.checkpoint,
            "device": self.device,
        }

    def validate_config_update(
        self, old_config: Dict[str, Any], new_config: Dict[str, Any]
    ) -> None:
        if "model_name" in new_config:
            raise ValueError(
                "The model name cannot be changed after the embedding function has been initialized."
            )
        if "checkpoint" in new_config:
            raise ValueError(
                "The checkpoint cannot be changed after the embedding function has been initialized."
            )

    @staticmethod
    def validate_config(config: Dict[str, Any]) -> None:
        """
        Validate the configuration using the JSON schema.

        Args:
            config: Configuration to validate

        Raises:
            ValidationError: If the configuration does not match the schema
        """
        validate_config_schema(config, "open_clip")

View on GitHub (pinned to aecdd12c8a)

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

Example fix

// before
new_cfg = fn.get_config(); new_cfg["checkpoint"] = "laion2b_s32b_b82k"
fn.validate_config_update(fn.get_config(), new_cfg)  # ValueError

// after
fn2 = OpenCLIPEmbeddingFunction(model_name="ViT-B-32", checkpoint="laion2b_s32b_b82k")
col2 = client.create_collection("imgs_vitb32_s32b_b82k", embedding_function=fn2)
# migrate images from the old collection

Defensive patterns

Strategy: validation

Validate before calling

def assert_checkpoint_update_safe(new_config: dict) -> None:
    if "checkpoint" in new_config:
        raise ValueError("checkpoint is immutable; rebuild the collection with new weights")

Try / catch

try:
    fn.validate_config_update(old_cfg, new_cfg)
except ValueError as e:
    if "checkpoint cannot be changed" in str(e):
        new_cfg.pop("checkpoint", None)  # or trigger re-embed migration
    else:
        raise

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/735499ef0b44428a. Report an issue: GitHub.