{"record":{"id":"179b6fa6a76585d6","repo":"chroma-core/chroma","slug":"cannot-change-the-model-of-the-embedding-function-179b6f","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/VoyageAIEmbeddingFunction.ts","lineNumber":114,"sourceCode":"  }\n\n  buildFromConfig(config: StoredConfig): VoyageAIEmbeddingFunction {\n    return new VoyageAIEmbeddingFunction({\n      api_key_env_var: config.api_key_env_var,\n      model: config.model_name,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      api_key_env_var: this.apiKeyEnvVar,\n      model_name: this.model,\n    };\n  }\n\n  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {\n    if (oldConfig.model_name !== newConfig.model_name) {\n      throw new Error(\"Cannot change the model of the embedding function.\");\n    }\n  }\n\n  validateConfig(config: StoredConfig): void {\n    validateConfigSchema(config, \"voyageai\");\n  }\n}\n","sourceCodeStart":96,"sourceCodeEnd":122,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/VoyageAIEmbeddingFunction.ts#L96-L122","documentation":"VoyageAIEmbeddingFunction.validateConfigUpdate() compares the stored `model_name` with the new one during collection.modify()/updateCollection and rejects any change. As with all Chroma embedding functions, the model determines vector dimensionality (voyage-2 = 1024d, voyage-lite = 512d, voyage-3 = 1024d, ...), so it is immutable after collection creation.","triggerScenarios":"collection.modify({ embedding_function: new VoyageAIEmbeddingFunction({ model: 'voyage-3' }) }) on a collection created with 'voyage-2'; client.updateCollection passing a config whose model_name string differs from the stored one (including 'voyage-2' vs 'voyage-02' typos).","commonSituations":"Upgrading to a newer Voyage model (voyage-2 -> voyage-3) and assuming in-place migration works; different defaults across team members' code; case/whitespace differences in the model string.","solutions":["Create a new collection with the new model and re-embed: read documents/metadata from the old collection with get(), add() them to the new one, then delete the old collection.","If the modify was unintentional, pass exactly the model the collection was created with (check the old function's getConfig()).model_name)."],"exampleFix":"// before\nawait collection.modify({\n  embedding_function: new VoyageAIEmbeddingFunction({ model: \"voyage-3\" }),\n}); // collection created with \"voyage-2\" -> throws\n\n// after\nconst { ids, documents, metadatas } = await oldCollection.get();\nconst upgraded = await client.createCollection({\n  name: `${oldCollection.name}-voyage3`,\n  embeddingFunction: new VoyageAIEmbeddingFunction({ model: \"voyage-3\" }),\n});\nawait upgraded.add({ ids, documents, metadatas });","handlingStrategy":"validation","validationCode":"const oldModel = oldFn.getConfig().model_name;\nif (newFn.getConfig().model_name !== oldModel) {\n  throw new Error(`Voyage model change (${oldModel} -> ${newFn.getConfig().model_name}) requires a new collection; vectors have different dimensions.`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Read the existing model via getConfig() before any collection.modify() that touches embedding settings.","Centralize model names in one config constant so creation and update paths cannot disagree."],"tags":["voyageai","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"}