chroma-core/chroma · error · ValueError

The instructions cannot be changed after the embedding funct

Error message

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

What it means

validate_config_update for chroma-cloud-qwen raises ValueError when 'instructions' appears in new_config (checked last, after model and task). Instructions map tasks to per-target prompt strings that are sent to the Qwen embedding API; they are fixed at construction, so updates are rejected to keep stored and future embeddings consistent.

Source

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

            "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

        Raises:
            ValidationError: If the configuration does not match the schema
        """
        validate_config_schema(config, "chroma-cloud-qwen")

View on GitHub (pinned to aecdd12c8a)

Solutions

Remove 'instructions' from the update payload — no chroma-cloud-qwen keys are mutable.
Instantiate a new ChromaCloudQwenEmbeddingFunction with the changed instructions dict and use it with a new collection.
Treat prompt/instruction changes like model changes: re-embed everything that must stay comparable.

Example fix

# before
new_config = {"instructions": {"nl_to_code": {"query": "better prompt"}}}  # ValueError

# after
ef = ChromaCloudQwenEmbeddingFunction(
    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,
    task="nl_to_code",
    instructions={"nl_to_code": {ChromaCloudQwenEmbeddingTarget.QUERY: "better prompt"}},
)

Defensive patterns

Strategy: validation

Validate before calling

if "instructions" in new_config:
    raise ValueError(
        "instructions are immutable for chroma-cloud-qwen; pass them to the constructor instead"
    )

Type guard

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

Prevention

Version prompt changes like code: new function instance, new collection, re-embed.
Keep instruction dicts in constants and pass them at construction only.
Exclude model/task/instructions in any generic config-diff tooling before it submits updates.

When it happens

Trigger: An EF config update where new_config contains the 'instructions' key and neither 'model' nor 'task' is present. Example: submitting {"instructions": {"nl_to_code": {"query": "..."}}} after the collection was created.

Common situations: Iterating on retrieval prompts by editing config instead of recreating the function; deserializing a full config snapshot and submitting it as an update; copying examples that pass get_config() verbatim.

Related errors

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