{"record":{"id":"ee620116794c592b","repo":"chroma-core/chroma","slug":"defaultembeddingfunction-model-cannot-be-changed-a","errorCode":null,"errorMessage":"DefaultEmbeddingFunction model cannot be changed after initialization.","messagePattern":"DefaultEmbeddingFunction model cannot be changed after initialization\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/DefaultEmbeddingFunction.ts","lineNumber":96,"sourceCode":"  getConfig(): StoredConfig {\n    return {\n      model: this.model,\n      revision: this.revision,\n      quantized: this.quantized,\n    };\n  }\n\n  buildFromConfig(config: StoredConfig): DefaultEmbeddingFunction {\n    return new DefaultEmbeddingFunction({\n      model: config.model,\n      revision: config.revision,\n      quantized: config.quantized,\n    });\n  }\n\n  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {\n    if (oldConfig.model !== newConfig.model) {\n      throw new Error(\n        \"DefaultEmbeddingFunction model cannot be changed after initialization.\",\n      );\n    }\n  }\n\n  validateConfig(config: StoredConfig): void {\n    validateConfigSchema(config, \"transformers\");\n  }\n\n  private async loadClient() {\n    if (this.transformersApi) return;\n    try {\n      // eslint-disable-next-line global-require,import/no-extraneous-dependencies\n      let { pipeline } = await DefaultEmbeddingFunction.import();\n      TransformersApi = pipeline;\n    } catch (_a) {\n      // @ts-ignore\n      if (_a.code === \"MODULE_NOT_FOUND\") {","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/DefaultEmbeddingFunction.ts#L78-L114","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Leave model unchanged in update payloads (or omit the embedding_function block entirely).","To change models, create a new collection configured with the new model and re-embed your corpus.","Persist the creation-time model name with your collection metadata and diff it against any planned update before calling modify."],"exampleFix":"// before\nawait col.modify({\n  configuration: { embedding_function: { model: 'Xenova/all-MiniLM-L6-v2' } },\n});\n\n// after: new collection, same default model\nconst newCol = await client.createCollection({\n  name: 'docs-v2',\n  embeddingFunction: new DefaultEmbeddingFunction({ model: 'Xenova/all-MiniLM-L6-v2' }),\n});\n// re-embed and migrate documents, then retire the old collection","handlingStrategy":"validation","validationCode":"const currentModel = 'BAAI/bge-small-en-v1.5'; // model the collection was created with\nconst desiredModel = config.model ?? 'BAAI/bge-small-en-v1.5';\nif (desiredModel !== currentModel) {\n  throw new Error(\n    `Cannot switch DefaultEmbeddingFunction model to ${desiredModel}; create a new collection and re-embed`,\n  );\n}\nawait col.modify({ configuration: { embedding_function: { model: desiredModel } } });","typeGuard":null,"tryCatchPattern":"try {\n  await col.modify({ configuration: { embedding_function: { model } } });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('model cannot be changed after initialization')) {\n    // keep the original model, or migrate to a new collection\n  }\n  throw e;\n}","preventionTips":["Omit model from update payloads when you do not intend to change the EF.","Record the ONNX model name in collection metadata at creation time.","Validate updates with ef.validateConfigUpdate(oldConfig, newConfig) yourself before calling modify."],"tags":["embeddings","default-embedding","onnx","configuration","immutable-field","model-change"],"backgroundTag":"immutable-config","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}