chroma-core/chroma · error · Error

DefaultEmbeddingFunction model cannot be changed after initi

Error message

DefaultEmbeddingFunction model cannot be changed after initialization.

What it means

DefaultEmbeddingFunction (the ONNX/transformers.js default EF) implements validateConfigUpdate and throws when newConfig.model differs from oldConfig.model - e.g. switching from 'BAAI/bge-small-en-v1.5' to another model. The rationale is the same as for other EFs: vectors from different models are not comparable, so an existing collection's embedding model is immutable; changing it requires a new collection.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/DefaultEmbeddingFunction.ts:96

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

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

  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {
    if (oldConfig.model !== newConfig.model) {
      throw new Error(
        "DefaultEmbeddingFunction model cannot be changed after initialization.",
      );
    }
  }

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

  private async loadClient() {
    if (this.transformersApi) return;
    try {
      // eslint-disable-next-line global-require,import/no-extraneous-dependencies
      let { pipeline } = await DefaultEmbeddingFunction.import();
      TransformersApi = pipeline;
    } catch (_a) {
      // @ts-ignore
      if (_a.code === "MODULE_NOT_FOUND") {

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Leave model unchanged in update payloads (or omit the embedding_function block entirely).
  2. To change models, create a new collection configured with the new model and re-embed your corpus.
  3. Persist the creation-time model name with your collection metadata and diff it against any planned update before calling modify.

Example fix

// before
await col.modify({
  configuration: { embedding_function: { model: 'Xenova/all-MiniLM-L6-v2' } },
});

// after: new collection, same default model
const newCol = await client.createCollection({
  name: 'docs-v2',
  embeddingFunction: new DefaultEmbeddingFunction({ model: 'Xenova/all-MiniLM-L6-v2' }),
});
// re-embed and migrate documents, then retire the old collection
Defensive patterns

Strategy: validation

Validate before calling

const currentModel = 'BAAI/bge-small-en-v1.5'; // model the collection was created with
const desiredModel = config.model ?? 'BAAI/bge-small-en-v1.5';
if (desiredModel !== currentModel) {
  throw new Error(
    `Cannot switch DefaultEmbeddingFunction model to ${desiredModel}; create a new collection and re-embed`,
  );
}
await col.modify({ configuration: { embedding_function: { model: desiredModel } } });

Try / catch

try {
  await col.modify({ configuration: { embedding_function: { model } } });
} catch (e) {
  if (e instanceof Error && e.message.includes('model cannot be changed after initialization')) {
    // keep the original model, or migrate to a new collection
  }
  throw e;
}

Prevention

When it happens

Trigger: Updating a collection's embedding_function config with { model: 'Xenova/all-MiniLM-L6-v2', ... } when the collection was created with the default 'BAAI/bge-small-en-v1.5'; template configs that always specify a model different from the creation-time default.

Common situations: Teams standardizing on a smaller/larger ONNX model after initial rollout; copying config snippets from docs that use a different default model; upgrading client versions whose bundled default changed.

Related errors

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