chroma-core/chroma · error · ValueError

Embedding function not found. Add…

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.

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
• An embedding function already exists in the collection…
• Cannot update embedding function: incompatible types
• Cloudflare Workers AI only supports text documents, not…
• Could not build embedding function

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

Appendix: 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)