{"record":{"id":"90fa4a76dcf6d3ac","repo":"chroma-core/chroma","slug":"failed-to-register-sparse-embedding-function-e","errorCode":null,"errorMessage":"Failed to register sparse embedding function: {e}","messagePattern":"Failed to register sparse embedding function: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/__init__.py","lineNumber":235,"sourceCode":"    return _register\n\n\ndef register_sparse_embedding_function(ef_class=None):  # type: ignore\n    \"\"\"Register a custom sparse embedding function.\n\n    Can be used as a decorator:\n        @register_sparse_embedding_function\n        class MySparseEmbeddingFunction(SparseEmbeddingFunction):\n            @classmethod\n            def name(cls): return \"my_sparse_embedding\"\n    \"\"\"\n\n    def _register(cls):  # type: ignore\n        try:\n            name = cls.name()\n            sparse_known_embedding_functions[name] = cls\n        except Exception as e:\n            raise ValueError(f\"Failed to register sparse embedding function: {e}\")\n        return cls  # Return the class unchanged\n\n    if ef_class is not None:\n        return _register(ef_class)  # type: ignore\n\n    return _register\n\n\n# Function to convert config to embedding function\ndef config_to_embedding_function(config: Dict[str, Any]) -> EmbeddingFunction:  # type: ignore\n    \"\"\"Convert a config dictionary to an embedding function.\n\n    Args:\n        config: The config dictionary.\n\n    Returns:\n        The embedding function.\n    \"\"\"","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/__init__.py#L217-L253","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add @staticmethod def name() -> str returning a unique stable identifier (e.g. \"my_sparse_embedding\").","Subclass chromadb.api.types.SparseEmbeddingFunction and implement its full protocol before decorating.","Inspect the embedded {e} text to find the underlying exception and fix that (usually AttributeError on name)."],"exampleFix":"# before: ValueError \"Failed to register sparse embedding function: ...\"\n@register_sparse_embedding_function\nclass MySparseEF(SparseEmbeddingFunction):\n    ...\n\n# after\n@register_sparse_embedding_function\nclass MySparseEF(SparseEmbeddingFunction):\n    @staticmethod\n    def name() -> str:\n        return \"my_sparse_ef\"\n    ...","handlingStrategy":"validation","validationCode":"from chromadb.api.types import SparseEmbeddingFunction\n\ndef assert_registerable_sparse(cls) -> None:\n    name_fn = getattr(cls, \"name\", None)\n    if not callable(name_fn):\n        raise TypeError(f\"{cls.__name__} must define a static name() method\")\n    if not isinstance(name_fn(), str) or not name_fn():\n        raise TypeError(f\"{cls.__name__}.name() must return a non-empty string\")\n\nassert_registerable_sparse(MySparseEF)\nregister_sparse_embedding_function(MySparseEF)","typeGuard":"def is_registerable_sparse_ef(cls) -> bool:\n    name_fn = getattr(cls, \"name\", None)\n    if not callable(name_fn):\n        return False\n    try:\n        return isinstance(name_fn(), str) and len(name_fn()) > 0\n    except Exception:\n        return False","tryCatchPattern":"try:\n    register_sparse_embedding_function(MySparseEF)\nexcept ValueError as e:\n    raise RuntimeError(f\"Cannot register sparse EF {MySparseEF.__name__}: fix name(): {e}\") from e","preventionTips":["Subclass SparseEmbeddingFunction and implement name() as a @staticmethod with a literal string.","Run registration at import time in the module that defines the class so failures surface in CI immediately.","Assert the registry actually contains your name after registering: known check via sparse_known_embedding_functions."],"tags":["python","sparse-embedding","embedding-functions","registry","plugin-registration","chromadb"],"backgroundTag":"plugin-registration-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}