chroma-core/chroma · error · Error

Cannot change the revision of the embedding function.

Error message

Cannot change the revision of the embedding function.

What it means

Same validateConfigUpdate() guard in TransformersEmbeddingFunction, but for the pinned model `revision` (the Hugging Face commit/tag the weights are pulled from). Different revisions of the same model can produce different vector spaces, so Chroma forbids changing revision after collection creation even when the model name is identical.

Source

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

      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. Keep the revision identical to the collection's original config when modifying other settings; check getConfig() on the old function to see the stored value.
2. To actually change revision, create a new collection with the pinned revision and re-add the documents, since vectors may not be comparable across revisions.

Example fix

// before
await collection.modify({
  embedding_function: new TransformersEmbeddingFunction({ model, revision: "refs/pr/13" }),
});

// after (keep the original revision)
await collection.modify({
  embedding_function: new TransformersEmbeddingFunction({ model, revision: "main" }), // same as creation-time config
});

const oldCfg = oldFn.getConfig();
const newCfg = newFn.getConfig();
if (oldCfg.revision !== newCfg.revision) {
  throw new Error(`Revision change (${oldCfg.revision} -> ${newCfg.revision}) is forbidden; pin the original revision or create a new collection.`);
}

When it happens

Trigger: collection.modify()/updateCollection with a TransformersEmbeddingFunction whose `revision` differs from creation time — e.g., created with revision 'main' (default) and updated with an explicit commit hash like 'refs/pr/2', or vice versa.

Common situations: Pinning revisions for reproducibility after a collection was created unpinned; code drift between environments where one passes revision and the other relies on the default; re-running setup scripts that now pin a revision.

Related errors

• Cannot change the model 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/9f69e9aca0761db9. Report an issue: GitHub.