chroma-core/chroma · error · ValueError

Failed to register embedding function: {e}

Error message

Failed to register embedding function: {e}

What it means

register_embedding_function adds a custom embedding function class to chromadb's registry (known_embedding_functions) keyed by cls.name(). The inner _register wraps the whole operation in try/except Exception, so any failure while obtaining the name — class has no name() method, name() raises internally, or name() returns something unhashable/None — is re-raised as ValueError with the original exception embedded in {e}. Because it usually runs as a decorator, the error fires at class-definition (import) time.

Source

Thrown at chromadb/utils/embedding_functions/__init__.py:209

    Can be used as a decorator:
        @register_embedding_function
        class MyEmbedding(EmbeddingFunction):
            @classmethod
            def name(cls): return "my_embedding"

    Or directly:
        register_embedding_function(MyEmbedding)

    Args:
        ef_class: The embedding function class to register.
    """

    def _register(cls):  # type: ignore
        try:
            name = cls.name()
            known_embedding_functions[name] = cls
        except Exception as e:
            raise ValueError(f"Failed to register embedding function: {e}")
        return cls  # Return the class unchanged

    # If called with a class, register it immediately
    if ef_class is not None:
        return _register(ef_class)  # type: ignore

    # If called without arguments, return a decorator
    return _register


def register_sparse_embedding_function(ef_class=None):  # type: ignore
    """Register a custom sparse embedding function.

    Can be used as a decorator:
        @register_sparse_embedding_function
        class MySparseEmbeddingFunction(SparseEmbeddingFunction):
            @classmethod
            def name(cls): return "my_sparse_embedding"

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Define a stable name on the class: @staticmethod\n def name() -> str: return "my_embedding".
2. Subclass chromadb.api.types.EmbeddingFunction and implement the full contract (name(), get_config(), build_from_config(), validate_config()) before registering.
3. Read the {e} portion of the message — it carries the original exception (e.g. AttributeError: type object has no attribute 'name') and points at the exact defect.

Example fix

# before: raises ValueError "Failed to register embedding function: type object 'MyEF' has no attribute 'name'"
@register_embedding_function
class MyEF(EmbeddingFunction):
    def __call__(self, input):
        ...

# after
@register_embedding_function
class MyEF(EmbeddingFunction):
    @staticmethod
    def name() -> str:
        return "my_ef"

    def __call__(self, input):
        ...

from chromadb.api.types import EmbeddingFunction

def assert_registerable(cls) -> None:
    name_fn = getattr(cls, "name", None)
    if not callable(name_fn):
        raise TypeError(f"{cls.__name__} must define a static name() method")
    name = name_fn()
    if not isinstance(name, str) or not name:
        raise TypeError(f"{cls.__name__}.name() must return a non-empty string")

assert_registerable(MyEF)
register_embedding_function(MyEF)

def is_registerable_ef(cls) -> bool:
    name_fn = getattr(cls, "name", None)
    if not callable(name_fn):
        return False
    try:
        return isinstance(name_fn(), str) and len(name_fn()) > 0
    except Exception:
        return False

# Prefer the direct-call form over the decorator so a bad class never breaks module import
try:
    register_embedding_function(MyEF)
except ValueError as e:
    raise RuntimeError(f"Cannot register {MyEF.__name__}: fix name(): {e}") from e

When it happens

Trigger: Applying @register_embedding_function (or calling register_embedding_function(MyEF)) to a class that does not define a name() classmethod/staticmethod, or whose name() raises — e.g. it depends on instance state, missing config, or external services.

Common situations: Custom embedding functions written without subclassing EmbeddingFunction or without its required static methods; refactors that rename or delete name(); name() implemented as an instance method that touches self attributes.

Related errors

• Failed to register sparse embedding function: {e}
• Unsupported embedding function: {name}
• Config must contain a 'name' field.
• Keyword argument {key} is not a primitive type
• The model name cannot be changed after the embedding functio

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