{"record":{"id":"eff34c572abb459c","repo":"chroma-core/chroma","slug":"failed-to-register-embedding-function-e","errorCode":null,"errorMessage":"Failed to register embedding function: {e}","messagePattern":"Failed to register embedding function: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/__init__.py","lineNumber":209,"sourceCode":"    Can be used as a decorator:\n        @register_embedding_function\n        class MyEmbedding(EmbeddingFunction):\n            @classmethod\n            def name(cls): return \"my_embedding\"\n\n    Or directly:\n        register_embedding_function(MyEmbedding)\n\n    Args:\n        ef_class: The embedding function class to register.\n    \"\"\"\n\n    def _register(cls):  # type: ignore\n        try:\n            name = cls.name()\n            known_embedding_functions[name] = cls\n        except Exception as e:\n            raise ValueError(f\"Failed to register embedding function: {e}\")\n        return cls  # Return the class unchanged\n\n    # If called with a class, register it immediately\n    if ef_class is not None:\n        return _register(ef_class)  # type: ignore\n\n    # If called without arguments, return a decorator\n    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\"","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/__init__.py#L191-L227","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Define a stable name on the class: @staticmethod\\n def name() -> str: return \"my_embedding\".","Subclass chromadb.api.types.EmbeddingFunction and implement the full contract (name(), get_config(), build_from_config(), validate_config()) before registering.","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."],"exampleFix":"# before: raises ValueError \"Failed to register embedding function: type object 'MyEF' has no attribute 'name'\"\n@register_embedding_function\nclass MyEF(EmbeddingFunction):\n    def __call__(self, input):\n        ...\n\n# after\n@register_embedding_function\nclass MyEF(EmbeddingFunction):\n    @staticmethod\n    def name() -> str:\n        return \"my_ef\"\n\n    def __call__(self, input):\n        ...","handlingStrategy":"validation","validationCode":"from chromadb.api.types import EmbeddingFunction\n\ndef assert_registerable(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    name = name_fn()\n    if not isinstance(name, str) or not name:\n        raise TypeError(f\"{cls.__name__}.name() must return a non-empty string\")\n\nassert_registerable(MyEF)\nregister_embedding_function(MyEF)","typeGuard":"def is_registerable_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":"# Prefer the direct-call form over the decorator so a bad class never breaks module import\ntry:\n    register_embedding_function(MyEF)\nexcept ValueError as e:\n    raise RuntimeError(f\"Cannot register {MyEF.__name__}: fix name(): {e}\") from e","preventionTips":["Subclass chromadb.api.types.EmbeddingFunction so the full contract is checked.","Implement name() as a @staticmethod returning a hardcoded string — no state, no I/O.","Unit-test that importing your EF module registers successfully in a clean interpreter."],"tags":["python","embedding-functions","registry","decorator","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"}