chroma-core/chroma · error · ValueError

Failed to register sparse embedding function: {e}

Error message

Failed to register sparse embedding function: {e}

What it means

The sparse twin of register_embedding_function: it inserts a class into sparse_known_embedding_functions after calling cls.name(), and wraps any exception from that call as this ValueError. It exists so sparse embedding functions (BM25, SPLADE-style encoders) can be resolved by name during config deserialization. The error almost always means the decorated class does not satisfy the SparseEmbeddingFunction contract, specifically a working name() classmethod.

Source

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

    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"
    """

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

    if ef_class is not None:
        return _register(ef_class)  # type: ignore

    return _register


# Function to convert config to embedding function
def config_to_embedding_function(config: Dict[str, Any]) -> EmbeddingFunction:  # type: ignore
    """Convert a config dictionary to an embedding function.

    Args:
        config: The config dictionary.

    Returns:
        The embedding function.
    """

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Add @staticmethod def name() -> str returning a unique stable identifier (e.g. "my_sparse_embedding").
2. Subclass chromadb.api.types.SparseEmbeddingFunction and implement its full protocol before decorating.
3. Inspect the embedded {e} text to find the underlying exception and fix that (usually AttributeError on name).

Example fix

# before: ValueError "Failed to register sparse embedding function: ..."
@register_sparse_embedding_function
class MySparseEF(SparseEmbeddingFunction):
    ...

# after
@register_sparse_embedding_function
class MySparseEF(SparseEmbeddingFunction):
    @staticmethod
    def name() -> str:
        return "my_sparse_ef"
    ...

from chromadb.api.types import SparseEmbeddingFunction

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

assert_registerable_sparse(MySparseEF)
register_sparse_embedding_function(MySparseEF)

def is_registerable_sparse_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

try:
    register_sparse_embedding_function(MySparseEF)
except ValueError as e:
    raise RuntimeError(f"Cannot register sparse EF {MySparseEF.__name__}: fix name(): {e}") from e

When it happens

Trigger: Applying @register_sparse_embedding_function to a class missing a name() static/classmethod, or whose name() raises; also calling register_sparse_embedding_function(cls) programmatically on such a class.

Common situations: Porting a dense custom embedding function to sparse and forgetting the name() method; copy-pasting a class that implemented name() as a property; name() that reads environment or module state unavailable at import time.

Related errors

• Failed to register 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/90fa4a76dcf6d3ac. Report an issue: GitHub.