chroma-core/chroma · error · ValueError

Cannot update embedding function: incompatible types ({exist

Error message

Cannot update embedding function: incompatible types ({existing_embedding_function.name()} vs {update_embedding_function.name()})

What it means

This ValueError from overwrite_embedding_function is raised when a collection-configuration update supplies an embedding function whose name() differs from the embedding function already attached to the collection. Chroma only permits updating the configuration (e.g. model name) of the SAME embedding function class, because swapping to a different function type would make all stored embeddings incomparable.

Source

Thrown at chromadb/api/collection_configuration.py:705

# TODO: make warnings prettier and add link to migration docs
def overwrite_embedding_function(
    existing_embedding_function: EmbeddingFunction,  # type: ignore
    update_embedding_function: EmbeddingFunction,  # type: ignore
) -> EmbeddingFunction:  # type: ignore
    """Overwrite an EmbeddingFunction with a new configuration"""
    # Check for legacy embedding functions
    if existing_embedding_function.is_legacy() or update_embedding_function.is_legacy():
        warnings.warn(
            "cannot update legacy embedding function config",
            DeprecationWarning,
            stacklevel=2,
        )
        return existing_embedding_function

    # Validate function compatibility
    if existing_embedding_function.name() != update_embedding_function.name():
        raise ValueError(
            f"Cannot update embedding function: incompatible types "
            f"({existing_embedding_function.name()} vs {update_embedding_function.name()})"
        )

    # Validate and apply the configuration update
    update_embedding_function.validate_config_update(
        existing_embedding_function.get_config(), update_embedding_function.get_config()
    )
    return update_embedding_function


def overwrite_collection_configuration(
    existing_config: CollectionConfiguration,
    update_config: UpdateCollectionConfiguration,
) -> CollectionConfiguration:
    """Overwrite a CollectionConfiguration with a new configuration"""
    update_spann = update_config.get("spann")
    update_hnsw = update_config.get("hnsw")

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Keep the same embedding function type; only update its configurable parameters (model name, api key, etc.) via modify
2. To move to a genuinely different embedding function, create a NEW collection with the new EF and re-embed all documents from source data
3. Check the persisted EF name first (collection.configuration['embedding_function']['name']) and compare with the update's name before calling modify

Example fix

// before
# collection created with default ONNXMiniLM_L6_V2
collection.modify(configuration={
    'embedding_function': {
        'name': 'all-mpnet-base-v2', 'type': 'known', 'config': {}
    }
})  # ValueError: incompatible types

// after
new_col = client.create_collection(
    name='docs_v2',
    embedding_function=SentenceTransformerEmbeddingFunction(model_name='all-mpnet-base-v2'),
)
new_col.add(documents=source_docs, ids=source_ids)

def can_update_ef(collection_ef_name: str, new_ef_name: str) -> bool:
    return collection_ef_name == new_ef_name

persisted_name = (collection.configuration or {}).get('embedding_function', {}).get('name')
if can_update_ef(persisted_name, new_ef.name()):
    collection.modify(configuration={'embedding_function': {'name': new_ef.name(), 'type': 'known', 'config': new_ef.get_config()}})
else:
    raise SystemExit('different EF: create a new collection and re-embed instead')

def is_same_embedding_function(existing_name: str, update_name: str) -> bool:
    return existing_name == update_name

try:
    collection.modify(configuration=update)
except ValueError as e:
    if 'Cannot update embedding function: incompatible types' in str(e):
        # fall back to recreate-and-reingest strategy
        migrate_to_new_collection(collection, new_ef)
    else:
        raise

When it happens

Trigger: Creating a collection with ONNXMiniLM_L6_V2 (the default) and then calling collection.modify(configuration={'embedding_function': {'name': 'all-MiniLM-L6-v2', 'type': 'known', 'config': {...different model...}}}), or passing an UpdateCollectionConfiguration whose embedding_function is an instance of a different EmbeddingFunction class than the persisted one.

Common situations: Teams upgrading embedding models in place and expecting modify to re-index existing data; copying an update config from a collection created with a different EF; switching between OpenAIEmbeddingFunction and SentenceTransformerEmbeddingFunction on an existing collection.

Related errors

• Embedding function provided when already defined in the coll
• Multiple embedding functions provided. Please provide only o
• An embedding function already exists in the collection confi
• Invalid URL. Unrecognized protocol - {parsed.scheme}.
• Invalid URL. Seems that you are trying to pass URL as a host

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