chroma-core/chroma · error · ValueError

The dimension cannot be changed after the embedding function

Error message

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

What it means

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.

Source

Thrown at chromadb/utils/embedding_functions/google_embedding_function.py:179

            "vertexai": self.vertexai,
            "project": self.project,
            "location": self.location,
        }
        if self.task_type is not None:
            config["task_type"] = self.task_type
        if self.dimension is not None:
            config["dimension"] = self.dimension
        return config

    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 "dimension" in new_config:
            raise ValueError(
                "The dimension cannot be changed after the embedding function has been initialized."
            )
        if "vertexai" in new_config:
            raise ValueError(
                "The vertexai cannot be changed after the embedding function has been initialized."
            )
        if "project" in new_config:
            raise ValueError(
                "The project cannot be changed after the embedding function has been initialized."
            )
        if "location" in new_config:
            raise ValueError(
                "The location cannot be changed after the embedding function has been initialized."
            )

    @staticmethod
    def validate_config(config: Dict[str, Any]) -> None:
        """

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Recreate the collection with the new dimension and re-embed all documents
2. If you only need to change other settings, remove the 'dimension' key from the update payload
3. Plan dimension up front (gemini-embedding-001 supports 128-3072 via MRL) before initial ingestion

Example fix

# before
update = ef.get_config()          # includes "dimension": 768
update["task_type"] = "RETRIEVAL_QUERY"
ef.validate_config_update(old, update)  # ValueError: dimension immutable

# after
update = {"task_type": "RETRIEVAL_QUERY"}  # only mutable keys
ef.validate_config_update(old, update)

IMMUTABLE = {"model_name", "dimension", "vertexai", "project", "location"}

update = {k: v for k, v in desired_config.items() if k not in IMMUTABLE}
assert "dimension" not in update
ef.validate_config_update(old_config, update)

from typing import Any, TypeGuard

MUTABLE_GEMINI_KEYS = {"api_key_env_var", "task_type"}

def is_mutable_update(cfg: Any) -> TypeGuard[dict]:
    return isinstance(cfg, dict) and set(cfg) <= MUTABLE_GEMINI_KEYS

When it happens

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

Common situations: Adopting Matryoshka truncated dimensions to save memory after data was already embedded; copying full configs as update payloads; model+dimension migrations attempted in place.

Related errors

• The model name cannot be changed after the embedding functio
• The vertexai cannot be changed after the embedding function
• Updating '{key}' is not supported for {NAME}
• The google-genai python package is not installed. Please ins
• Vertex AI and API key are mutually exclusive in the client i

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