chroma-core/chroma · error · Error

Cannot change the model of the embedding function.

Error message

Cannot change the model of the embedding function.

What it means

VoyageAIEmbeddingFunction.validateConfigUpdate() compares the stored `model_name` with the new one during collection.modify()/updateCollection and rejects any change. As with all Chroma embedding functions, the model determines vector dimensionality (voyage-2 = 1024d, voyage-lite = 512d, voyage-3 = 1024d, ...), so it is immutable after collection creation.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/VoyageAIEmbeddingFunction.ts:114

  }

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

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

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

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

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Create a new collection with the new model and re-embed: read documents/metadata from the old collection with get(), add() them to the new one, then delete the old collection.
2. If the modify was unintentional, pass exactly the model the collection was created with (check the old function's getConfig()).model_name).

Example fix

// before
await collection.modify({
  embedding_function: new VoyageAIEmbeddingFunction({ model: "voyage-3" }),
}); // collection created with "voyage-2" -> throws

// after
const { ids, documents, metadatas } = await oldCollection.get();
const upgraded = await client.createCollection({
  name: `${oldCollection.name}-voyage3`,
  embeddingFunction: new VoyageAIEmbeddingFunction({ model: "voyage-3" }),
});
await upgraded.add({ ids, documents, metadatas });

const oldModel = oldFn.getConfig().model_name;
if (newFn.getConfig().model_name !== oldModel) {
  throw new Error(`Voyage model change (${oldModel} -> ${newFn.getConfig().model_name}) requires a new collection; vectors have different dimensions.`);
}

When it happens

Trigger: collection.modify({ embedding_function: new VoyageAIEmbeddingFunction({ model: 'voyage-3' }) }) on a collection created with 'voyage-2'; client.updateCollection passing a config whose model_name string differs from the stored one (including 'voyage-2' vs 'voyage-02' typos).

Common situations: Upgrading to a newer Voyage model (voyage-2 -> voyage-3) and assuming in-place migration works; different defaults across team members' code; case/whitespace differences in the model string.

Related errors

• Cannot change the model of the embedding function.
• Cannot change the revision of the embedding function.
• Cannot change the quantization of the embedding function.
• VoyageAI API key is required. Please provide it in the const
• Please install the voyageai package to use the VoyageAIEmbed

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