chroma-core/chroma · error · ChromaValueError

Instructions cannot be updated

Error message

Instructions cannot be updated

What it means

Thrown as a ChromaValueError by ChromaCloudQwenEmbeddingFunction.validateConfigUpdate() when an update payload contains the key "instructions". The instruction strings per task/target are part of how every existing vector in the collection was produced, so they cannot be changed in place.

Source

Thrown at clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/src/index.ts:258

    return {
      model: this.model,
      task: this.task,
      instructions: serializedInstructions as any,
      api_key_env_var: this.apiKeyEnvVar,
    };
  }

  public validateConfigUpdate(newConfig: Record<string, any>): void {
    if ("model" in newConfig) {
      throw new ChromaValueError("Model cannot be updated");
    }

    if ("task" in newConfig) {
      throw new ChromaValueError("Task cannot be updated");
    }

    if ("instructions" in newConfig) {
      throw new ChromaValueError("Instructions cannot be updated");
    }
  }

  public static validateConfig(config: ChromaCloudQwenConfig): void {
    validateConfigSchema(config, NAME);
  }
}

registerEmbeddingFunction(NAME, ChromaCloudQwenEmbeddingFunction);

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Remove "instructions" from the update payload.
2. Create a new collection with the customized instructions and re-embed the data.
3. Pass custom instructions at construction time only.

Example fix

// before
await collection.modify({
  embedding_function: { name: "chroma-cloud-qwen", config: { instructions: { nl_to_code: { documents: "", query: "custom" } } } },
});

// after
const ef = new ChromaCloudQwenEmbeddingFunction({
  model: ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,
  task: "nl_to_code",
  instructions: { nl_to_code: { documents: "", query: "custom" } },
});
const col = await client.createCollection({ name: "docs-custom-instr", embeddingFunction: ef });

const patch = { ...desiredUpdate };
delete patch.instructions;
if (Object.keys(desiredUpdate).includes("instructions")) {
  console.warn("'instructions' is immutable and was stripped; recreate the collection to change it");
}

When it happens

Trigger: Attempting to update the EF config with { instructions: {...} }; pasting the output of getConfig() (which serializes instructions) directly into an update payload.

Common situations: Tuning prompt-style instructions and trying to apply them to an existing collection; automated tooling that diffs and re-submits whole configs.

Related errors

• Model cannot be updated
• Task cannot be updated
• Config is missing a required field
• The model name cannot be changed after initialization.
• The task type cannot be changed after initialization.

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