{"record":{"id":"5a7788b787c345a8","repo":"chroma-core/chroma","slug":"the-model-name-cannot-be-changed-after-initializat","errorCode":null,"errorMessage":"The model name cannot be changed after initialization.","messagePattern":"The model name cannot be changed after initialization\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/GoogleGeminiEmbeddingFunction.ts","lineNumber":121,"sourceCode":"      apiKeyEnvVar: config.api_key_env_var,\n      taskType: config.task_type,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      api_key_env_var: this.api_key_env_var,\n      model_name: this.model,\n      task_type: this.taskType,\n    };\n  }\n\n  validateConfigUpdate(\n    oldConfig: Record<string, any>,\n    newConfig: Record<string, any>,\n  ): void {\n    if (oldConfig.model_name !== newConfig.model_name) {\n      throw new Error(\"The model name cannot be changed after initialization.\");\n    }\n\n    if (oldConfig.taskType !== newConfig.taskType) {\n      throw new Error(\"The task type cannot be changed after initialization.\");\n    }\n  }\n\n  validateConfig(config: Record<string, any>): void {\n    validateConfigSchema(config, \"google_generative_ai\");\n  }\n}\n","sourceCodeStart":103,"sourceCodeEnd":133,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/GoogleGeminiEmbeddingFunction.ts#L103-L133","documentation":"Chroma validates changes to an embedding configuration by calling validateConfigUpdate(oldConfig, newConfig). The Google embedding function refuses model_name changes: vectors already stored in the collection were produced by the old model, and mixing embedding spaces silently corrupts similarity search. The model is therefore pinned for the life of the collection's config.","triggerScenarios":"An embedding-config update where newConfig.model_name differs from oldConfig.model_name — e.g. re-creating the function with model: \"text-embedding-004\" and applying it to a collection embedded with \"embedding-001\". Other fields may still be updated; only model_name is checked here.","commonSituations":"Upgrading Gemini embedding model versions in an existing deployment; per-environment config templates injecting different model names onto existing collections; hand-edited config backups being restored.","solutions":["Keep model_name identical: fetch the stored getConfig() first and reuse its model_name when updating other fields","If the model must change, create a NEW collection with the new model and re-embed all source documents into it (backfill job)","If the existing data is disposable, delete and recreate the collection with the new model"],"exampleFix":"// before: bumping the model on an existing collection\nconst ef = new GoogleGenerativeAiEmbeddingFunction({ googleApiKey: KEY, model: \"text-embedding-004\" });\n// validateConfigUpdate(old{model_name:'embedding-001'}, new{model_name:'text-embedding-004'}) -> throws\n\n// after: new collection per model\nconst v2 = await client.createCollection({ name: \"docs-embedding-004\", embeddingFunction: ef });\nawait v2.add({ ids, documents }); // re-embed from source","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 this BEFORE requesting the config update, using getConfig() output as oldCfg","typeGuard":null,"tryCatchPattern":"try {\n  await applyConfigUpdate(collection, newCfg);\n} catch (e) {\n  if (e instanceof Error && /model name cannot be changed/i.test(e.message)) {\n    // route to the create-new-collection + re-embed path instead of retrying\n  }\n  throw e;\n}","preventionTips":["Encode the embedding model in collection names (docs-embedding-001) so mismatches are visible","Persist the exact config used at collection creation and reuse it verbatim on updates","Treat the embedding model as schema: version it with new collections, never mutate it"],"tags":["embeddings","config","google","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"}