{"record":{"id":"ecef19a202215a69","repo":"chroma-core/chroma","slug":"cannot-update-embedding-function-incompatible-typ","errorCode":null,"errorMessage":"Cannot update embedding function: incompatible types ({existing_embedding_function.name()} vs {update_embedding_function.name()})","messagePattern":"Cannot update embedding function: incompatible types \\((.+?) vs (.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/collection_configuration.py","lineNumber":705,"sourceCode":"\n# TODO: make warnings prettier and add link to migration docs\ndef overwrite_embedding_function(\n    existing_embedding_function: EmbeddingFunction,  # type: ignore\n    update_embedding_function: EmbeddingFunction,  # type: ignore\n) -> EmbeddingFunction:  # type: ignore\n    \"\"\"Overwrite an EmbeddingFunction with a new configuration\"\"\"\n    # Check for legacy embedding functions\n    if existing_embedding_function.is_legacy() or update_embedding_function.is_legacy():\n        warnings.warn(\n            \"cannot update legacy embedding function config\",\n            DeprecationWarning,\n            stacklevel=2,\n        )\n        return existing_embedding_function\n\n    # Validate function compatibility\n    if existing_embedding_function.name() != update_embedding_function.name():\n        raise ValueError(\n            f\"Cannot update embedding function: incompatible types \"\n            f\"({existing_embedding_function.name()} vs {update_embedding_function.name()})\"\n        )\n\n    # Validate and apply the configuration update\n    update_embedding_function.validate_config_update(\n        existing_embedding_function.get_config(), update_embedding_function.get_config()\n    )\n    return update_embedding_function\n\n\ndef overwrite_collection_configuration(\n    existing_config: CollectionConfiguration,\n    update_config: UpdateCollectionConfiguration,\n) -> CollectionConfiguration:\n    \"\"\"Overwrite a CollectionConfiguration with a new configuration\"\"\"\n    update_spann = update_config.get(\"spann\")\n    update_hnsw = update_config.get(\"hnsw\")","sourceCodeStart":687,"sourceCodeEnd":723,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/collection_configuration.py#L687-L723","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Keep the same embedding function type; only update its configurable parameters (model name, api key, etc.) via modify","To move to a genuinely different embedding function, create a NEW collection with the new EF and re-embed all documents from source data","Check the persisted EF name first (collection.configuration['embedding_function']['name']) and compare with the update's name before calling modify"],"exampleFix":"// before\n# collection created with default ONNXMiniLM_L6_V2\ncollection.modify(configuration={\n    'embedding_function': {\n        'name': 'all-mpnet-base-v2', 'type': 'known', 'config': {}\n    }\n})  # ValueError: incompatible types\n\n// after\nnew_col = client.create_collection(\n    name='docs_v2',\n    embedding_function=SentenceTransformerEmbeddingFunction(model_name='all-mpnet-base-v2'),\n)\nnew_col.add(documents=source_docs, ids=source_ids)","handlingStrategy":"validation","validationCode":"def can_update_ef(collection_ef_name: str, new_ef_name: str) -> bool:\n    return collection_ef_name == new_ef_name\n\npersisted_name = (collection.configuration or {}).get('embedding_function', {}).get('name')\nif can_update_ef(persisted_name, new_ef.name()):\n    collection.modify(configuration={'embedding_function': {'name': new_ef.name(), 'type': 'known', 'config': new_ef.get_config()}})\nelse:\n    raise SystemExit('different EF: create a new collection and re-embed instead')","typeGuard":"def is_same_embedding_function(existing_name: str, update_name: str) -> bool:\n    return existing_name == update_name","tryCatchPattern":"try:\n    collection.modify(configuration=update)\nexcept ValueError as e:\n    if 'Cannot update embedding function: incompatible types' in str(e):\n        # fall back to recreate-and-reingest strategy\n        migrate_to_new_collection(collection, new_ef)\n    else:\n        raise","preventionTips":["Treat embedding-function TYPE as immutable per collection; only tweak its config","Store the EF identity alongside collection names in app config so get/modify always use the matching class","Automate re-embedding pipelines instead of attempting in-place model swaps"],"tags":["chroma","embedding-function","modify-collection","incompatible-types","configuration"],"backgroundTag":"embedding-function-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}