chroma-core/chroma · error · Error

Cannot change model name.

Error message

Cannot change model name.

What it means

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

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts:203

      openai_api_key: config.api_key_env_var,
      openai_model: config.model_name,
      openai_organization_id: config.organization_id,
      openai_embedding_dimensions: config.dimensions,
    });
  }

  getConfig(): StoredConfig {
    return {
      api_key_env_var: this.api_key,
      model_name: this.model,
      organization_id: this.org_id,
      dimensions: this.dimensions ?? 1536,
    };
  }

  validateConfigUpdate(oldConfig: StoredConfig, newConfig: StoredConfig): void {
    if (oldConfig.model_name !== newConfig.model_name) {
      throw new Error("Cannot change model name.");
    }
  }

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

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Reuse the stored model_name for updates; change only the other fields
2. Create a new collection with the new model and re-embed the documents (usually a scripted backfill)
3. Delete and recreate the collection if the existing data is disposable

Example fix

// before: changing the model on an existing collection
const ef = new OpenAIEmbeddingFunction({ openai_api_key: KEY, openai_model: "text-embedding-3-small" });
// validateConfigUpdate(old{model_name:'text-embedding-ada-002'}, new{...3-small}) -> throws

// after: new collection per model
const v2 = await client.createCollection({ name: "docs-3-small", embeddingFunction: ef });
await v2.add({ ids, documents });

function assertCompatibleUpdate(oldCfg: Record<string, any>, newCfg: Record<string, any>): void {
  if (oldCfg.model_name !== newCfg.model_name) {
    throw new Error(`model_name is immutable (${oldCfg.model_name} -> ${newCfg.model_name}); create a new collection instead`);
  }
}
// call before requesting the config update, with oldCfg from getConfig()

try {
  await applyConfigUpdate(collection, newCfg);
} catch (e) {
  if (e instanceof Error && /Cannot change model name/.test(e.message)) {
    // model differs: route to create-new-collection + re-embed; retrying the update cannot succeed
  }
  throw e;
}

When it happens

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

Common situations: Migrating OpenAI embedding model versions; config templates injecting different model names per environment onto existing collections; restoring hand-edited config backups.

Related errors

• The model name cannot be changed after initialization.
• The task type cannot be changed after initialization.
• Changing the URL is not allowed.
• Config is missing a required field
• OpenAI API key is required. Please provide it in the constru

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