{"record":{"id":"259abcce0e314391","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-the-embeddi-259abc","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/jina_embedding_function.py","lineNumber":268,"sourceCode":"\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            \"task\": self.task,\n            \"late_chunking\": self.late_chunking,\n            \"truncate\": self.truncate,\n            \"dimensions\": self.dimensions,\n            \"embedding_type\": self.embedding_type,\n            \"normalized\": self.normalized,\n            \"query_config\": self.query_config,\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, \"jina\")\n","sourceCodeStart":250,"sourceCodeEnd":284,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/jina_embedding_function.py#L250-L284","documentation":"Chroma embedding functions support config-based reconfiguration, but JinaEmbeddingFunction.validate_config_update rejects any update payload that contains the key 'model_name', raising this ValueError. Changing the model would silently change the vector space of already-stored embeddings, corrupting similarity search, so the field is immutable by design. All other config keys (task, late_chunking, truncate, dimensions, embedding_type, normalized, query_config) may be updated.","triggerScenarios":"Calling the EF/collection config-update API with {'model_name': 'jina-clip-v2', ...}; deserializing and re-applying a full get_config() dict that round-trips model_name back into an update; UI/tooling that PUTs the entire config instead of only changed keys.","commonSituations":"Migrating to a new Jina model by attempting an in-place config edit; config-sync tooling that sends whole config objects; copy-pasting get_config() output into an update call during debugging.","solutions":["Create a new embedding function / new collection for the new model and re-index, rather than updating in place","Strip immutable keys before updating: new_config.pop('model_name', None)","Diff old vs new config and only send genuinely changed, mutable keys"],"exampleFix":"# before\nnew_config = ef.get_config()\nnew_config[\"model_name\"] = \"jina-clip-v2\"\nef.validate_config_update(ef.get_config(), new_config)  # ValueError\n\n# after\nnew_config = {k: v for k, v in ef.get_config().items() if k != \"model_name\"}\nnew_config[\"dimensions\"] = 512\nef.validate_config_update(ef.get_config(), new_config)  # ok","handlingStrategy":"validation","validationCode":"IMMUTABLE = {\"model_name\"}\n\ndef safe_update(ef, new_config: dict) -> dict:\n    illegal = IMMUTABLE & new_config.keys()\n    if illegal:\n        raise ValueError(\n            f\"cannot update immutable keys {illegal}; create a new EF/collection instead\"\n        )\n    ef.validate_config_update(ef.get_config(), new_config)\n    return new_config","typeGuard":null,"tryCatchPattern":"try:\n    ef.validate_config_update(old_config, new_config)\nexcept ValueError as e:\n    if \"cannot be changed\" in str(e):\n        new_config = {k: v for k, v in new_config.items() if k != \"model_name\"}\n        ef.validate_config_update(old_config, new_config)\n    else:\n        raise","preventionTips":["Send only the diff of changed keys in config updates, never a full get_config() echo","Treat model changes as re-indexing migrations with a new collection","Centralize update payloads through a helper that strips immutable keys"],"tags":["python","configuration","immutable-field","jina","config-update"],"backgroundTag":"immutable-configuration","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}