chroma-core/chroma · error · ValueError

Embedding function {ef_name} not found. Add @register_embedd

Error message

Embedding function {ef_name} not found. Add @register_embedding_function decorator to the class definition.

What it means

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.

Source

Thrown at chromadb/api/collection_configuration.py:98

        ef_config = config_json_map["embedding_function"]
        if ef_config["type"] == "legacy":
            warnings.warn(
                "legacy embedding function config",
                DeprecationWarning,
                stacklevel=2,
            )
            ef = None
        else:
            try:
                ef_name = ef_config["name"]
            except KeyError:
                raise ValueError(
                    f"Embedding function name not found in config: {ef_config}"
                )
            try:
                ef = known_embedding_functions[ef_name]
            except KeyError:
                raise ValueError(
                    f"Embedding function {ef_name} not found. Add @register_embedding_function decorator to the class definition."
                )
            try:
                validate_embedding_function_config_is_safe(ef_name, ef_config["config"])
                ef = ef.build_from_config(ef_config["config"])  # type: ignore
            except Exception as e:
                raise ValueError(
                    f"Could not build embedding function {ef_config['name']} from config {ef_config['config']}: {e}"
                )
    else:
        ef = None

    return CollectionConfiguration(
        hnsw=hnsw_config,
        spann=spann_config,
        embedding_function=ef,  # type: ignore
    )

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Import the custom embedding function module and decorate its class with @register_embedding_function before creating/fetching the client in the failing process.
2. If the EF was renamed in a chromadb upgrade, pin the old version or recreate the collection with the current EF name.
3. Recreate the collection with a built-in embedding function if the custom one is no longer available.

Example fix

# before
import chromadb
client = chromadb.HttpClient()
client.get_collection("docs")  # ValueError: MyEF not found

# after
from chromadb.utils.embedding_functions import register_embedding_function

@register_embedding_function
class MyEF(chromadb.EmbeddingFunction[Documents]):
    ...

client = chromadb.HttpClient()
client.get_collection("docs")

from chromadb.utils.embedding_functions import known_embedding_functions

def ef_registered(name: str) -> bool:
    return name in known_embedding_functions

# probe before loading (peek at the stored config name first)
assert ef_registered("MyEF"), "import and @register_embedding_function MyEF first"

from chromadb.utils.embedding_functions import known_embedding_functions
import chromadb.api.types as t

def is_loadable_ef_config(config: dict) -> bool:
    ef = config.get("embedding_function")
    if not ef or ef.get("type") == "legacy":
        return True
    return ef.get("name") in known_embedding_functions

try:
    col = client.get_collection("docs")
except ValueError as e:
    if "not found. Add @register_embedding_function" in str(e):
        raise RuntimeError("register the custom embedding function before get_collection") from e
    raise

When it happens

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

Common situations: 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.

Related errors

• Embedding function name not found in config: {ef_config}
• Embedding function provided when already defined in the coll
• hnsw and spann cannot both be provided
• Could not build embedding function {ef_config['name']} from
• not a valid hnsw config: {e}

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