{"record":{"id":"b40bcaab1e3e1707","repo":"chroma-core/chroma","slug":"the-model-cannot-be-changed-after-the-embedding-fu-b40bca","errorCode":null,"errorMessage":"The model cannot be changed after the embedding function has been initialized.","messagePattern":"The model cannot be changed after the embedding function has been initialized\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/nomic_embedding_function.py","lineNumber":117,"sourceCode":"            model=model,\n            api_key_env_var=api_key_env_var,\n            task_type=task_type,\n            query_config=query_config,\n        )\n\n    def get_config(self) -> Dict[str, Any]:\n        return {\n            \"model\": self.model,\n            \"api_key_env_var\": self.api_key_env_var,\n            \"task_type\": self.task_type,\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\" in new_config:\n            raise ValueError(\n                \"The model 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        validate_config_schema(config, \"nomic\")\n","sourceCodeStart":99,"sourceCodeEnd":130,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/nomic_embedding_function.py#L99-L130","documentation":"NomicEmbeddingFunction implements Chroma's embedding-function configuration protocol: get_config() serializes its constructor params and validate_config_update() rejects any update that includes the \"model\" key. Because embeddings for a given collection must stay dimensionally and semantically compatible, the model is pinned at creation; changing nomic-embed-text-v1 to v1.5 after documents were embedded would silently poison the index, so Chroma refuses it.","triggerScenarios":"Calling the EF config-update API path with a new config dict containing {\"model\": ...} (e.g. via collection-level EF reconfiguration or the config-management flow that calls validate_config_update(old_config, new_config)); attempting to reuse a persisted EF config while swapping only the model field.","commonSituations":"Upgrading from nomic-embed-text-v1 to nomic-embed-text-v1.5 and trying to hot-swap the model on an existing collection; editing EF config JSON by hand and including the model key; tooling that round-trips get_config() output and mutates model before reapplying it.","solutions":["Create a NEW embedding function (and typically a new collection) with the desired model instead of updating the existing one","Re-embed all documents into the new collection, then delete the old one: read docs from the old collection, add them with the new EF","Remove the \"model\" key from the update payload if you only meant to change other fields (none are currently mutable for Nomic besides rebuilding)"],"exampleFix":"// before (rejected)\nnew_config = fn.get_config(); new_config[\"model\"] = \"nomic-embed-text-v1.5\"\nfn.validate_config_update(fn.get_config(), new_config)  # ValueError\n\n// after\nfn_v15 = NomicEmbeddingFunction(model=\"nomic-embed-text-v1.5\", task_type=\"search_document\", query_config={\"task_type\": \"search_query\"})\ncol2 = client.create_collection(\"docs_v15\", embedding_function=fn_v15)\nfor batch in col.get(include=[\"documents\",\"metadatas\"])[\"documents\"]: ...  # re-ingest","handlingStrategy":"validation","validationCode":"IMMUTABLE = {\"model\"}\ndef safe_ef_update(fn, new_config: dict) -> dict:\n    blocked = IMMUTABLE & set(new_config)\n    if blocked:\n        raise ValueError(f\"Cannot update immutable EF keys {blocked}; create a new collection instead\")\n    return new_config","typeGuard":null,"tryCatchPattern":"try:\n    fn.validate_config_update(old_config, new_config)\nexcept ValueError as e:\n    if \"cannot be changed\" in str(e):\n        # branch to migration path: new collection + re-embed\n        ...\n    raise","preventionTips":["Treat model as part of collection identity: name collections after their model (e.g. docs_nomic_v1_5)","Never mutate get_config() output before reapplying it","Script model migrations as create-new-collection + re-ingest, not config updates"],"tags":["nomic","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"}