{"record":{"id":"2cfc724fc65480fc","repo":"chroma-core/chroma","slug":"cohereembeddingfunction-model-name-cannot-be-chang","errorCode":null,"errorMessage":"CohereEmbeddingFunction model_name cannot be changed after initialization.","messagePattern":"CohereEmbeddingFunction model_name cannot be changed after initialization\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/CohereEmbeddingFunction.ts","lineNumber":185,"sourceCode":"  }\n\n  buildFromConfig(config: StoredConfig): CohereEmbeddingFunction {\n    return new CohereEmbeddingFunction({\n      model: config.model_name,\n      cohere_api_key_env_var: config.api_key_env_var,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      model_name: this.model,\n      api_key_env_var: this.apiKeyEnvVar,\n    };\n  }\n\n  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {\n    if (oldConfig.model_name !== newConfig.model_name) {\n      throw new Error(\n        \"CohereEmbeddingFunction model_name cannot be changed after initialization.\",\n      );\n    }\n  }\n\n  validateConfig(config: StoredConfig): void {\n    validateConfigSchema(config, \"cohere\");\n  }\n\n  supportedSpaces(): EmbeddingFunctionSpace[] {\n    if (this.model === \"embed-english-v3.0\") {\n      return [\"cosine\", \"l2\", \"ip\"];\n    }\n\n    if (this.model === \"embed-english-light-v3.0\") {\n      return [\"cosine\", \"ip\", \"l2\"];\n    }\n","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/CohereEmbeddingFunction.ts#L167-L203","documentation":"CohereEmbeddingFunction.validateConfigUpdate compares oldConfig.model_name with newConfig.model_name and throws if they differ. Embedding vectors from different Cohere models live in incompatible spaces, so changing the model of an existing collection would silently corrupt similarity search; the client therefore forbids it (this is the optional validateConfigUpdate hook on IEmbeddingFunction, invoked when validating a configuration update against an existing collection).","triggerScenarios":"Applying an update whose embedding_function config carries a different model_name (e.g. embed-english-v3.0 -> embed-multilingual-v3.0); passing a full new configuration object built from a template that defaults a different model.","commonSituations":"Multi-language expansion attempts; environment-specific config files where prod uses a different model than the collection was created with; upgrading Cohere model versions in place.","solutions":["Keep model_name identical in the updated configuration (omit it or repeat the original value).","To switch models, create a NEW collection with the new model and re-embed all documents, then cut over reads/writes.","Compare old/new configs yourself (old.model_name === new.model_name) before submitting the update."],"exampleFix":"// before\nawait col.modify({\n  configuration: { embedding_function: { model_name: 'embed-multilingual-v3.0', api_key_env_var: 'CHROMA_COHERE_API_KEY' } },\n}); // collection was created with embed-english-v3.0\n\n// after: migrate to a new collection\nconst newCol = await client.createCollection({\n  name: 'docs-v2',\n  embeddingFunction: new CohereEmbeddingFunction({ model_name: 'embed-multilingual-v3.0' }),\n});\n// re-add documents to newCol, then drop the old collection","handlingStrategy":"validation","validationCode":"const oldConfig = col.configuration; // or your persisted creation-time config\nconst newEfConfig = { model_name: 'embed-english-v3.0', api_key_env_var: 'CHROMA_COHERE_API_KEY' };\nif (oldConfig?.model_name && oldConfig.model_name !== newEfConfig.model_name) {\n  throw new Error(\n    `Cannot change Cohere model from ${oldConfig.model_name} to ${newEfConfig.model_name}; create a new collection instead`,\n  );\n}\nawait col.modify({ configuration: { embedding_function: newEfConfig } });","typeGuard":null,"tryCatchPattern":"try {\n  await col.modify({ configuration: { embedding_function: newCfg } });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('model_name cannot be changed')) {\n    // plan a migration: create new collection with the target model and re-embed\n  }\n  throw e;\n}","preventionTips":["Pin the model_name in one shared constant used for both creation and updates.","Store the creation-time embedding config in collection metadata for later comparison.","Treat model changes as a data migration (new collection + re-embed), never an in-place update."],"tags":["embeddings","cohere","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"}