chroma-core/chroma · error · Error

CohereEmbeddingFunction model_name cannot be changed after i

Error message

CohereEmbeddingFunction model_name cannot be changed after initialization.

What it means

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).

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/CohereEmbeddingFunction.ts:185

  }

  buildFromConfig(config: StoredConfig): CohereEmbeddingFunction {
    return new CohereEmbeddingFunction({
      model: config.model_name,
      cohere_api_key_env_var: config.api_key_env_var,
    });
  }

  getConfig(): StoredConfig {
    return {
      model_name: this.model,
      api_key_env_var: this.apiKeyEnvVar,
    };
  }

  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {
    if (oldConfig.model_name !== newConfig.model_name) {
      throw new Error(
        "CohereEmbeddingFunction model_name cannot be changed after initialization.",
      );
    }
  }

  validateConfig(config: StoredConfig): void {
    validateConfigSchema(config, "cohere");
  }

  supportedSpaces(): EmbeddingFunctionSpace[] {
    if (this.model === "embed-english-v3.0") {
      return ["cosine", "l2", "ip"];
    }

    if (this.model === "embed-english-light-v3.0") {
      return ["cosine", "ip", "l2"];
    }

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

// before
await col.modify({
  configuration: { embedding_function: { model_name: 'embed-multilingual-v3.0', api_key_env_var: 'CHROMA_COHERE_API_KEY' } },
}); // collection was created with embed-english-v3.0

// after: migrate to a new collection
const newCol = await client.createCollection({
  name: 'docs-v2',
  embeddingFunction: new CohereEmbeddingFunction({ model_name: 'embed-multilingual-v3.0' }),
});
// re-add documents to newCol, then drop the old collection

Defensive patterns

Strategy: validation

Validate before calling

const oldConfig = col.configuration; // or your persisted creation-time config
const newEfConfig = { model_name: 'embed-english-v3.0', api_key_env_var: 'CHROMA_COHERE_API_KEY' };
if (oldConfig?.model_name && oldConfig.model_name !== newEfConfig.model_name) {
  throw new Error(
    `Cannot change Cohere model from ${oldConfig.model_name} to ${newEfConfig.model_name}; create a new collection instead`,
  );
}
await col.modify({ configuration: { embedding_function: newEfConfig } });

Try / catch

try {
  await col.modify({ configuration: { embedding_function: newCfg } });
} catch (e) {
  if (e instanceof Error && e.message.includes('model_name cannot be changed')) {
    // plan a migration: create new collection with the target model and re-embed
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/2cfc724fc65480fc. Report an issue: GitHub.