chroma-core/chroma · error · ValueError

The model name cannot be changed after the embedding functio

Error message

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

What it means

OllamaEmbeddingFunction.get_config() persists {url, model_name, timeout} and validate_config_update() rejects any update whose new_config contains the "model_name" key. Embedding models map text into a fixed vector space, so swapping the model after a collection has been embedded would make new vectors incomparable with stored ones; Chroma therefore makes model_name immutable while url/timeout remain updatable.

Source

Thrown at chromadb/utils/embedding_functions/ollama_embedding_function.py:102

    @staticmethod
    def build_from_config(config: Dict[str, Any]) -> "EmbeddingFunction[Documents]":
        url = config.get("url")
        model_name = config.get("model_name")
        timeout = config.get("timeout")

        if url is None or model_name is None or timeout is None:
            assert False, "This code should not be reached"

        return OllamaEmbeddingFunction(url=url, model_name=model_name, timeout=timeout)

    def get_config(self) -> Dict[str, Any]:
        return {"url": self.url, "model_name": self.model_name, "timeout": self.timeout}

    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."
            )

    @staticmethod
    def validate_config(config: Dict[str, Any]) -> None:
        """
        Validate the configuration using the JSON schema.

        Args:
            config: Configuration to validate

        Raises:
            ValidationError: If the configuration does not match the schema
        """
        validate_config_schema(config, "ollama")

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Create a new collection with the new model_name and re-ingest your documents (embeddings must be regenerated)
  2. If you only need to repoint the server, update "url" or "timeout" instead — only "model_name" is rejected
  3. Keep model choice out of mutable config; treat it as part of the collection's identity

Example fix

// before
new_cfg = fn.get_config(); new_cfg["model_name"] = "mxbai-embed-large"
fn.validate_config_update(fn.get_config(), new_cfg)  # ValueError

// after
col_new = client.create_collection("docs_mxbai", embedding_function=OllamaEmbeddingFunction(url="http://localhost:11434", model_name="mxbai-embed-large"))
# copy documents from the old collection into col_new
Defensive patterns

Strategy: validation

Validate before calling

def assert_ollama_update_allowed(new_config: dict) -> None:
    if "model_name" in new_config:
        raise ValueError("model_name is immutable; create a new collection to change models")
assert_ollama_update_allowed(my_new_config)

Try / catch

try:
    fn.validate_config_update(old_cfg, new_cfg)
except ValueError as e:
    if "model name cannot be changed" in str(e):
        new_cfg.pop("model_name", None)  # or start a migration
    else:
        raise

Prevention

When it happens

Trigger: Reconfiguring an existing collection's EF with {"model_name": "llama2"} via the config-update flow that calls validate_config_update(old, new); editing persisted EF config JSON and adding model_name; migrating from the default chroma/all-minilm-l6-v2-f32 to nomic-embed-text by update instead of rebuild.

Common situations: Trying out a new Ollama model (e.g. mxbai-embed-large) on an existing collection; config-management tooling that diffs get_config() output and pushes changed keys back; hand-edited config files in a GitOps pipeline.

Related errors

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