chroma-core/chroma · error · ValueError

The model cannot be changed after the embedding function has

Error message

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

What it means

ChromaCloudQwenEmbeddingFunction.validate_config_update raises ValueError the moment 'model' appears in new_config. The Qwen model determines the x-chroma-embedding-model header and the dimensionality of stored vectors, so changing it after initialization would make new embeddings incompatible with existing ones in the collection.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py:209

    def get_config(self) -> Dict[str, Any]:
        # Serialize instructions dict with enum keys to string keys for JSON compatibility
        serialized_instructions = {
            task: {target.value: instruction for target, instruction in targets.items()}
            for task, targets in self.instructions.items()
        }
        return {
            "api_key_env_var": self.api_key_env_var,
            "model": self.model.value,
            "task": self.task,
            "instructions": serialized_instructions,
        }

    def validate_config_update(
        self, old_config: Dict[str, Any], new_config: Dict[str, Any]
    ) -> None:
        if "model" in new_config:
            raise ValueError(
                "The model cannot be changed after the embedding function has been initialized."
            )
        elif "task" in new_config:
            raise ValueError(
                "The task cannot be changed after the embedding function has been initialized."
            )
        elif "instructions" in new_config:
            raise ValueError(
                "The instructions 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

View on GitHub (pinned to aecdd12c8a)

Solutions

Drop 'model' from the update config; chroma-cloud-qwen has no mutable keys, so only send keys you are allowed to change (none exist today).
To use a different model, create a new collection with a fresh ChromaCloudQwenEmbeddingFunction and re-embed your data.
If your tooling copies get_config() output, filter it to remove model/task/instructions before submitting an update.

Example fix

# before
new_config = ef.get_config()  # includes "model": "Qwen/Qwen3-Embedding-0.6B"
new_config["task"] = "nl_to_code"
# -> ValueError: model cannot be changed

# after
new_config = {"task": "nl_to_code"}  # still rejected: task also immutable -> recreate EF instead
ef = ChromaCloudQwenEmbeddingFunction(
    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,
    task="nl_to_code",
)

Defensive patterns

Strategy: validation

Validate before calling

IMMUTABLE_QWEN_KEYS = {"model", "task", "instructions"}
update = {k: v for k, v in new_config.items() if k not in IMMUTABLE_QWEN_KEYS}
if not update:
    raise ValueError("Nothing updatable for chroma-cloud-qwen; recreate the EF instead")

Type guard

def is_safe_qwen_update(new_config: dict) -> bool:
    return not ({"model", "task", "instructions"} & set(new_config))

Prevention

Treat model as immutable: plan migrations as new collection + re-embed, never as config edits.
Build update payloads as explicit minimal dicts, not snapshots of get_config().
Add a config filter helper shared by all update paths so immutable keys never slip through.

When it happens

Trigger: Updating the EF config for a collection initialized with chroma-cloud-qwen where new_config contains the 'model' key (even with the same value — presence alone triggers it, since the check is `if "model" in new_config`).

Common situations: Round-tripping a get_config() dict into an update call; migrating from one Qwen model to another via modify instead of a new collection; automation that sends the full config on every change.

Related errors

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