chroma-core/chroma · error · Error

Cannot change the model of the embedding function.

Error message

Cannot change the model of the embedding function.

What it means

TransformersEmbeddingFunction.validateConfigUpdate() runs when a collection's embedding configuration is updated (collection.modify / updateCollection with a new embedding function or config). Chroma pins the embedding model at collection creation because every stored vector's dimensionality comes from that model; changing it would make existing embeddings incomparable, so model is immutable. Only revision and quantized are likewise frozen; other fields may change.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts:128

  buildFromConfig(config: StoredConfig): TransformersEmbeddingFunction {
    return new TransformersEmbeddingFunction({
      model: config.model,
      revision: config.revision,
      quantized: config.quantized,
    });
  }

  getConfig(): StoredConfig {
    return {
      model: this.model,
      revision: this.revision,
      quantized: this.quantized,
    };
  }

  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {
    if (oldConfig.model !== newConfig.model) {
      throw new Error("Cannot change the model of the embedding function.");
    }
    if (oldConfig.revision !== newConfig.revision) {
      throw new Error("Cannot change the revision of the embedding function.");
    }
    if (oldConfig.quantized !== newConfig.quantized) {
      throw new Error(
        "Cannot change the quantization of the embedding function.",
      );
    }
  }

  validateConfig(config: StoredConfig): void {
    validateConfigSchema(config, "transformers");
  }
}

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Create a new collection with the new model, then re-embed and copy data: get() from the old collection, add() documents into the new one, then drop the old collection.
2. If the change was accidental, pass the original model string exactly as recorded in the collection's embedding configuration.

Example fix

// before (immutable -> throws)
await collection.modify({
  embedding_function: new TransformersEmbeddingFunction({ model: "Xenova/bge-base-en-v1.5" }),
});

// after (re-embed into a new collection)
const { documents, metadatas, ids } = await oldCollection.get();
const next = await client.createCollection({
  name: "docs-v2",
  embeddingFunction: new TransformersEmbeddingFunction({ model: "Xenova/bge-base-en-v1.5" }),
});
await next.add({ ids, documents, metadatas });
await client.deleteCollection({ name: oldCollection.name });

// Compare pinned config before attempting a modify
const oldCfg = oldFn.getConfig();
const newCfg = newFn.getConfig();
if (oldCfg.model !== newCfg.model) {
  throw new Error(`Model change (${oldCfg.model} -> ${newCfg.model}) requires a new collection and re-embedding.`);
}

When it happens

Trigger: collection.modify({ embedding_function: new TransformersEmbeddingFunction({ model: 'Xenova/bge-base-en-v1.5' }) }) on a collection created with model 'Xenova/all-MiniLM-L6-v2'; or client.updateCollection passing a config whose `model` string differs from the stored one.

Common situations: Attempting to 'migrate' a collection to a better embedding model in place; copy-pasting collection-creation code with a newer model into an update path; CI test fixtures created with an old model name.

Related errors

• Cannot change the revision of the embedding function.
• Cannot change the quantization of the embedding function.
• Cannot change the model of the embedding function.
• Please install the @xenova/transformers package to use the T
• Please install @xenova/transformers as a dependency with, e.

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