{"record":{"id":"9f69e9aca0761db9","repo":"chroma-core/chroma","slug":"cannot-change-the-revision-of-the-embedding-functi","errorCode":null,"errorMessage":"Cannot change the revision of the embedding function.","messagePattern":"Cannot change the revision of the embedding function\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts","lineNumber":131,"sourceCode":"      revision: config.revision,\n      quantized: config.quantized,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      model: this.model,\n      revision: this.revision,\n      quantized: this.quantized,\n    };\n  }\n\n  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {\n    if (oldConfig.model !== newConfig.model) {\n      throw new Error(\"Cannot change the model of the embedding function.\");\n    }\n    if (oldConfig.revision !== newConfig.revision) {\n      throw new Error(\"Cannot change the revision of the embedding function.\");\n    }\n    if (oldConfig.quantized !== newConfig.quantized) {\n      throw new Error(\n        \"Cannot change the quantization of the embedding function.\",\n      );\n    }\n  }\n\n  validateConfig(config: StoredConfig): void {\n    validateConfigSchema(config, \"transformers\");\n  }\n}\n","sourceCodeStart":113,"sourceCodeEnd":144,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts#L113-L144","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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."],"exampleFix":"// before\nawait collection.modify({\n  embedding_function: new TransformersEmbeddingFunction({ model, revision: \"refs/pr/13\" }),\n});\n\n// after (keep the original revision)\nawait collection.modify({\n  embedding_function: new TransformersEmbeddingFunction({ model, revision: \"main\" }), // same as creation-time config\n});","handlingStrategy":"validation","validationCode":"const oldCfg = oldFn.getConfig();\nconst newCfg = newFn.getConfig();\nif (oldCfg.revision !== newCfg.revision) {\n  throw new Error(`Revision change (${oldCfg.revision} -> ${newCfg.revision}) is forbidden; pin the original revision or create a new collection.`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass an explicit revision when creating transformers collections so later code can reproduce it exactly.","Record the revision in your collection registry/metadata to avoid guessing at update time."],"tags":["transformers","embeddings","immutable-config","model-revision","collection-update"],"backgroundTag":"embedding-model-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}