{"record":{"id":"7ff67e1718b12709","repo":"chroma-core/chroma","slug":"cannot-change-model-name","errorCode":null,"errorMessage":"Cannot change model name.","messagePattern":"Cannot change model name\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts","lineNumber":203,"sourceCode":"      openai_api_key: config.api_key_env_var,\n      openai_model: config.model_name,\n      openai_organization_id: config.organization_id,\n      openai_embedding_dimensions: config.dimensions,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      api_key_env_var: this.api_key,\n      model_name: this.model,\n      organization_id: this.org_id,\n      dimensions: this.dimensions ?? 1536,\n    };\n  }\n\n  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {\n    if (oldConfig.model_name !== newConfig.model_name) {\n      throw new Error(\"Cannot change model name.\");\n    }\n  }\n\n  validateConfig(config: StoredConfig): void {\n    validateConfigSchema(config, \"openai\");\n  }\n}\n","sourceCodeStart":185,"sourceCodeEnd":211,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts#L185-L211","documentation":"OpenAIEmbeddingFunction.validateConfigUpdate() rejects updates where model_name differs: existing vectors were embedded with the old OpenAI model (text-embedding-ada-002 vs text-embedding-3-small etc.), and different models produce incompatible embedding spaces, so the model is pinned per collection. (Grounded caveat: getConfig() stores the literal key under the field named api_key_env_var — a key/value naming bug — but model_name round-trips correctly and is what this check reads.)","triggerScenarios":"An embedding-config update on an existing collection after changing openai_model (e.g. ada-002 -> text-embedding-3-small); other fields may be updated, only model_name is compared.","commonSituations":"Migrating OpenAI embedding model versions; config templates injecting different model names per environment onto existing collections; restoring hand-edited config backups.","solutions":["Reuse the stored model_name for updates; change only the other fields","Create a new collection with the new model and re-embed the documents (usually a scripted backfill)","Delete and recreate the collection if the existing data is disposable"],"exampleFix":"// before: changing the model on an existing collection\nconst ef = new OpenAIEmbeddingFunction({ openai_api_key: KEY, openai_model: \"text-embedding-3-small\" });\n// validateConfigUpdate(old{model_name:'text-embedding-ada-002'}, new{...3-small}) -> throws\n\n// after: new collection per model\nconst v2 = await client.createCollection({ name: \"docs-3-small\", embeddingFunction: ef });\nawait v2.add({ ids, documents });","handlingStrategy":"validation","validationCode":"function assertCompatibleUpdate(oldCfg: Record<string, any>, newCfg: Record<string, any>): void {\n  if (oldCfg.model_name !== newCfg.model_name) {\n    throw new Error(`model_name is immutable (${oldCfg.model_name} -> ${newCfg.model_name}); create a new collection instead`);\n  }\n}\n// call before requesting the config update, with oldCfg from getConfig()","typeGuard":null,"tryCatchPattern":"try {\n  await applyConfigUpdate(collection, newCfg);\n} catch (e) {\n  if (e instanceof Error && /Cannot change model name/.test(e.message)) {\n    // model differs: route to create-new-collection + re-embed; retrying the update cannot succeed\n  }\n  throw e;\n}","preventionTips":["Name collections after the embedding model (docs-ada-002, docs-3-small) to make mismatches obvious","Persist and reuse the creation-time config verbatim for updates","Plan model migrations as new collections plus a re-embed backfill, never as config edits"],"tags":["embeddings","config","openai","immutable","validation"],"backgroundTag":"config-update-not-allowed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}