{"record":{"id":"c92f948b08c423d1","repo":"chroma-core/chroma","slug":"cannot-change-the-model-of-the-embedding-function","errorCode":null,"errorMessage":"Cannot change the model of the embedding function.","messagePattern":"Cannot change the model of the embedding function\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts","lineNumber":128,"sourceCode":"  buildFromConfig(config: StoredConfig): TransformersEmbeddingFunction {\n    return new TransformersEmbeddingFunction({\n      model: config.model,\n      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":110,"sourceCodeEnd":144,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts#L110-L144","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If the change was accidental, pass the original model string exactly as recorded in the collection's embedding configuration."],"exampleFix":"// before (immutable -> throws)\nawait collection.modify({\n  embedding_function: new TransformersEmbeddingFunction({ model: \"Xenova/bge-base-en-v1.5\" }),\n});\n\n// after (re-embed into a new collection)\nconst { documents, metadatas, ids } = await oldCollection.get();\nconst next = await client.createCollection({\n  name: \"docs-v2\",\n  embeddingFunction: new TransformersEmbeddingFunction({ model: \"Xenova/bge-base-en-v1.5\" }),\n});\nawait next.add({ ids, documents, metadatas });\nawait client.deleteCollection({ name: oldCollection.name });","handlingStrategy":"validation","validationCode":"// Compare pinned config before attempting a modify\nconst oldCfg = oldFn.getConfig();\nconst newCfg = newFn.getConfig();\nif (oldCfg.model !== newCfg.model) {\n  throw new Error(`Model change (${oldCfg.model} -> ${newCfg.model}) requires a new collection and re-embedding.`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Store each collection's creation-time embedding config alongside the collection name so updates can be diffed.","Treat embedding model changes as a migration: new collection, re-embed, then swap aliases."],"tags":["transformers","embeddings","immutable-config","collection-update"],"backgroundTag":"embedding-model-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}