{"record":{"id":"e7516ceef09bdc9a","repo":"chroma-core/chroma","slug":"the-instructions-cannot-be-changed-after-the-embed","errorCode":null,"errorMessage":"The instructions cannot be changed after the embedding function has been initialized.","messagePattern":"The instructions cannot be changed after the embedding function has been initialized\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py","lineNumber":217,"sourceCode":"            \"api_key_env_var\": self.api_key_env_var,\n            \"model\": self.model.value,\n            \"task\": self.task,\n            \"instructions\": serialized_instructions,\n        }\n\n    def validate_config_update(\n        self, old_config: Dict[str, Any], new_config: Dict[str, Any]\n    ) -> None:\n        if \"model\" in new_config:\n            raise ValueError(\n                \"The model cannot be changed after the embedding function has been initialized.\"\n            )\n        elif \"task\" in new_config:\n            raise ValueError(\n                \"The task cannot be changed after the embedding function has been initialized.\"\n            )\n        elif \"instructions\" in new_config:\n            raise ValueError(\n                \"The instructions cannot be changed after the embedding function has been initialized.\"\n            )\n\n    @staticmethod\n    def validate_config(config: Dict[str, Any]) -> None:\n        \"\"\"\n        Validate the configuration using the JSON schema.\n\n        Args:\n            config: Configuration to validate\n\n        Raises:\n            ValidationError: If the configuration does not match the schema\n        \"\"\"\n        validate_config_schema(config, \"chroma-cloud-qwen\")\n","sourceCodeStart":199,"sourceCodeEnd":233,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py#L199-L233","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nnew_config = {\"instructions\": {\"nl_to_code\": {\"query\": \"better prompt\"}}}  # ValueError\n\n# after\nef = ChromaCloudQwenEmbeddingFunction(\n    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,\n    task=\"nl_to_code\",\n    instructions={\"nl_to_code\": {ChromaCloudQwenEmbeddingTarget.QUERY: \"better prompt\"}},\n)","handlingStrategy":"validation","validationCode":"if \"instructions\" in new_config:\n    raise ValueError(\n        \"instructions are immutable for chroma-cloud-qwen; pass them to the constructor instead\"\n    )","typeGuard":"def is_safe_qwen_update(new_config: dict) -> bool:\n    return not ({\"model\", \"task\", \"instructions\"} & set(new_config))","tryCatchPattern":null,"preventionTips":["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."],"tags":["chroma-cloud","qwen","immutable-config","config-validation","embedding-function"],"backgroundTag":"immutable-config-update","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}