{"record":{"id":"2d59ee0c565ab40e","repo":"chroma-core/chroma","slug":"the-dimension-cannot-be-changed-after-the-embeddin","errorCode":null,"errorMessage":"The dimension cannot be changed after the embedding function has been initialized.","messagePattern":"The dimension cannot be changed after the embedding function has been initialized\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/google_embedding_function.py","lineNumber":179,"sourceCode":"            \"vertexai\": self.vertexai,\n            \"project\": self.project,\n            \"location\": self.location,\n        }\n        if self.task_type is not None:\n            config[\"task_type\"] = self.task_type\n        if self.dimension is not None:\n            config[\"dimension\"] = self.dimension\n        return config\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 \"dimension\" in new_config:\n            raise ValueError(\n                \"The dimension cannot be changed after the embedding function has been initialized.\"\n            )\n        if \"vertexai\" in new_config:\n            raise ValueError(\n                \"The vertexai cannot be changed after the embedding function has been initialized.\"\n            )\n        if \"project\" in new_config:\n            raise ValueError(\n                \"The project cannot be changed after the embedding function has been initialized.\"\n            )\n        if \"location\" in new_config:\n            raise ValueError(\n                \"The location cannot be changed after the embedding function has been initialized.\"\n            )\n\n    @staticmethod\n    def validate_config(config: Dict[str, Any]) -> None:\n        \"\"\"","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/google_embedding_function.py#L161-L197","documentation":"GoogleGeminiEmbeddingFunction.validate_config_update rejects update payloads containing a 'dimension' key. Output dimensionality is baked into every stored vector; changing it mid-life would produce vectors of a different length than the ones already in the collection, breaking index consistency, so it is treated as immutable.","triggerScenarios":"Attempting to change dimension (e.g. from 768 to 1536 or to MRL-truncated 256) via a config update on an existing collection; passing an ef.get_config() dict (which includes dimension when set) as the update payload.","commonSituations":"Adopting Matryoshka truncated dimensions to save memory after data was already embedded; copying full configs as update payloads; model+dimension migrations attempted in place.","solutions":["Recreate the collection with the new dimension and re-embed all documents","If you only need to change other settings, remove the 'dimension' key from the update payload","Plan dimension up front (gemini-embedding-001 supports 128-3072 via MRL) before initial ingestion"],"exampleFix":"# before\nupdate = ef.get_config()          # includes \"dimension\": 768\nupdate[\"task_type\"] = \"RETRIEVAL_QUERY\"\nef.validate_config_update(old, update)  # ValueError: dimension immutable\n\n# after\nupdate = {\"task_type\": \"RETRIEVAL_QUERY\"}  # only mutable keys\nef.validate_config_update(old, update)","handlingStrategy":"validation","validationCode":"IMMUTABLE = {\"model_name\", \"dimension\", \"vertexai\", \"project\", \"location\"}\n\nupdate = {k: v for k, v in desired_config.items() if k not in IMMUTABLE}\nassert \"dimension\" not in update\nef.validate_config_update(old_config, update)","typeGuard":"from typing import Any, TypeGuard\n\nMUTABLE_GEMINI_KEYS = {\"api_key_env_var\", \"task_type\"}\n\ndef is_mutable_update(cfg: Any) -> TypeGuard[dict]:\n    return isinstance(cfg, dict) and set(cfg) <= MUTABLE_GEMINI_KEYS","tryCatchPattern":null,"preventionTips":["Decide output dimensionality before first ingestion; changing it requires re-embedding into a new collection","Strip dimension from update payloads built from get_config()","Add a config-diff helper that whitelists mutable keys only"],"tags":["immutable-config","embedding-dimension","gemini","chroma"],"backgroundTag":"immutable-config-field","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}