{"record":{"id":"71b7ffe1746990a2","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-the-embeddi-71b7ff","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/perplexity_embedding_function.py","lineNumber":121,"sourceCode":"\n        return PerplexityEmbeddingFunction(\n            api_key_env_var=api_key_env_var,\n            model_name=model_name,\n            dimensions=dimensions,\n        )\n\n    def get_config(self) -> Dict[str, Any]:\n        return {\n            \"api_key_env_var\": self.api_key_env_var,\n            \"model_name\": self.model_name,\n            \"dimensions\": self.dimensions,\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\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, \"perplexity\")\n","sourceCodeStart":103,"sourceCodeEnd":137,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/perplexity_embedding_function.py#L103-L137","documentation":"PerplexityEmbeddingFunction.validate_config_update raises ValueError if the incoming configuration update dict contains \"model_name\". Chroma invokes this hook (chromadb/api/collection_configuration.py) when a collection's embedding function is being modified; the embedding model is immutable because switching it would make all previously stored Perplexity vectors incomparable with new ones. The check is a plain key-presence test, so even an unchanged model_name value in the payload is rejected.","triggerScenarios":"Calling collection.modify(...) with a replacement PerplexityEmbeddingFunction — its get_config() always returns model_name, so the update payload carries the key and the call raises. Only updates that omit model_name entirely can proceed.","commonSituations":"Trying to move from the default pplx-embed model to a newer release on an existing collection; attempting to change the Matryoshka dimensions by swapping the EF via modify; generic config tooling that diffs get_config() against a desired config and submits the whole dict.","solutions":["Create a new collection with the desired PerplexityEmbeddingFunction(model_name=..., dimensions=...) and re-index your documents into it.","If you intended to keep the model and only tweak other fields, submit an update config that excludes the model_name key.","Automate the migration: read old collection data, add to the new collection, verify counts, then delete the old one.","Pin the model choice at project start and record it alongside collection metadata so future upgrades are planned as re-indexes."],"exampleFix":"// before\ncollection.modify(\n    embedding_function=PerplexityEmbeddingFunction(model_name=\"pplx-embed-v1-0.6b\", dimensions=512)\n)  # ValueError: The model name cannot be changed after the embedding function has been initialized.\n\n# after\nnew_col = client.create_collection(\n    \"docs_pplx_v2\",\n    embedding_function=PerplexityEmbeddingFunction(model_name=\"pplx-embed-v1-0.6b\", dimensions=512),\n)\nfor batch in existing_col.get(limit=-1)[\"documents\"]:\n    new_col.add(...)  # re-embed with the new function","handlingStrategy":"validation","validationCode":"def strip_immutable_keys(new_config: dict) -> dict:\n    return {k: v for k, v in new_config.items() if k != \"model_name\"}\n\n# only pass mutable fields to the update path\nsafe_update = strip_immutable_keys(desired_config)","typeGuard":"def is_mutable_ef_update(new_config: dict) -> bool:\n    return \"model_name\" not in new_config","tryCatchPattern":"try:\n    collection.modify(embedding_function=new_pplx_ef)\nexcept ValueError as e:\n    if \"model name cannot be changed\" in str(e).lower():\n        raise RuntimeError(\"Re-create the collection with the new model and re-embed\") from e\n    raise","preventionTips":["Record the Perplexity model and dimensions in collection metadata at creation time.","Gate EF updates behind a whitelist of mutable keys (dimensions stays model-bound too — plan migrations).","Treat any model/dimension change as a re-index project, never an in-place modify."],"tags":["perplexity","embedding","model-name","immutable","collection-modify","chroma"],"backgroundTag":"immutable-config-update","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}