{"record":{"id":"b88125a14197674e","repo":"chroma-core/chroma","slug":"embedding-function-ef-name-not-found-add-regis","errorCode":null,"errorMessage":"Embedding function {ef_name} not found. Add @register_embedding_function decorator to the class definition.","messagePattern":"Embedding function (.+?) not found\\. Add @register_embedding_function decorator to the class definition\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/collection_configuration.py","lineNumber":98,"sourceCode":"        ef_config = config_json_map[\"embedding_function\"]\n        if ef_config[\"type\"] == \"legacy\":\n            warnings.warn(\n                \"legacy embedding function config\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n            ef = None\n        else:\n            try:\n                ef_name = ef_config[\"name\"]\n            except KeyError:\n                raise ValueError(\n                    f\"Embedding function name not found in config: {ef_config}\"\n                )\n            try:\n                ef = known_embedding_functions[ef_name]\n            except KeyError:\n                raise ValueError(\n                    f\"Embedding function {ef_name} not found. Add @register_embedding_function decorator to the class definition.\"\n                )\n            try:\n                validate_embedding_function_config_is_safe(ef_name, ef_config[\"config\"])\n                ef = ef.build_from_config(ef_config[\"config\"])  # type: ignore\n            except Exception as e:\n                raise ValueError(\n                    f\"Could not build embedding function {ef_config['name']} from config {ef_config['config']}: {e}\"\n                )\n    else:\n        ef = None\n\n    return CollectionConfiguration(\n        hnsw=hnsw_config,\n        spann=spann_config,\n        embedding_function=ef,  # type: ignore\n    )\n","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/collection_configuration.py#L80-L116","documentation":"The stored configuration names an embedding function (e.g. {\"embedding_function\": {\"type\": \"known\", \"name\": \"MyEF\", ...}}), but that name is absent from known_embedding_functions — the process-wide registry populated by the @register_embedding_function decorator. Built-ins are registered automatically; custom embedding functions must be registered in every process that loads the collection, before the collection is fetched.","triggerScenarios":"One service creates a collection with a custom EF; another service (or a worker, notebook, or fresh deploy) calls get_collection() without importing the custom EF class decorated with @register_embedding_function; the EF was renamed or removed in a chromadb upgrade.","commonSituations":"Writer/reader split in microservices where only the writer registers the custom EF; CI or notebooks loading collections created elsewhere; chromadb version bump dropping/renaming a built-in EF.","solutions":["Import the custom embedding function module and decorate its class with @register_embedding_function before creating/fetching the client in the failing process.","If the EF was renamed in a chromadb upgrade, pin the old version or recreate the collection with the current EF name.","Recreate the collection with a built-in embedding function if the custom one is no longer available."],"exampleFix":"# before\nimport chromadb\nclient = chromadb.HttpClient()\nclient.get_collection(\"docs\")  # ValueError: MyEF not found\n\n# after\nfrom chromadb.utils.embedding_functions import register_embedding_function\n\n@register_embedding_function\nclass MyEF(chromadb.EmbeddingFunction[Documents]):\n    ...\n\nclient = chromadb.HttpClient()\nclient.get_collection(\"docs\")","handlingStrategy":"validation","validationCode":"from chromadb.utils.embedding_functions import known_embedding_functions\n\ndef ef_registered(name: str) -> bool:\n    return name in known_embedding_functions\n\n# probe before loading (peek at the stored config name first)\nassert ef_registered(\"MyEF\"), \"import and @register_embedding_function MyEF first\"","typeGuard":"from chromadb.utils.embedding_functions import known_embedding_functions\nimport chromadb.api.types as t\n\ndef is_loadable_ef_config(config: dict) -> bool:\n    ef = config.get(\"embedding_function\")\n    if not ef or ef.get(\"type\") == \"legacy\":\n        return True\n    return ef.get(\"name\") in known_embedding_functions","tryCatchPattern":"try:\n    col = client.get_collection(\"docs\")\nexcept ValueError as e:\n    if \"not found. Add @register_embedding_function\" in str(e):\n        raise RuntimeError(\"register the custom embedding function before get_collection\") from e\n    raise","preventionTips":["Centralize custom EF definitions in one module and import it before any chromadb client use.","Decorate every custom EF with @register_embedding_function in all services that read the collection.","Pin chromadb versions so built-in EF names stay stable."],"tags":["chroma","embedding-function","registry","custom-ef","collection-configuration"],"backgroundTag":"unregistered-embedding-function","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}