{"record":{"id":"af64c37273d2bcbd","repo":"pathwaycom/pathway","slug":"embedder-is-not-a-valid-pw-udf","errorCode":null,"errorMessage":"Embedder is not a valid `pw.UDF`.","messagePattern":"Embedder is not a valid `pw\\.UDF`\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"python/pathway/stdlib/indexing/nearest_neighbors.py","lineNumber":420,"sourceCode":"            metadata_filter=metadata_filter,\n        )\n\n\n@dataclass(kw_only=True)\nclass KnnIndexFactory(InnerIndexFactory):\n    dimensions: int | None = None\n    embedder: pw.UDF | None = None\n\n    def _get_embed_dimensions(self) -> int:\n        # import is here to prevent cyclical imports\n        from pathway.xpacks.llm.embedders import BaseEmbedder\n\n        if isinstance(self.embedder, BaseEmbedder):\n            return self.embedder.get_embedding_dimension()\n        elif isinstance(self.embedder, pw.UDF):\n            return len(_coerce_sync(self.embedder.__wrapped__)(\".\"))\n        else:\n            raise TypeError(\"Embedder is not a valid `pw.UDF`.\")\n\n    def __post_init__(self):\n        if self.dimensions is None and self.embedder is not None:\n            self.dimensions: int = self._get_embed_dimensions()\n        elif self.dimensions is None and self.embedder is None:\n            raise ValueError(\n                \"Either `dimensions` or `embedder` must be provided to index factory.\"\n            )\n\n\n@dataclass(kw_only=True)\nclass UsearchKnnFactory(KnnIndexFactory):\n    \"\"\"\n    Factory for creating UsearchKNN indices.\n\n    Args:\n        dimensions (int): number of dimensions of vectors that are used by the index and\n            queries. This is only needed if the `embedder` is not provided.","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/stdlib/indexing/nearest_neighbors.py#L402-L438","documentation":"When a KnnIndexFactory (e.g. UsearchKnnFactory, BruteForceKnnFactory) is given an `embedder` but no explicit `dimensions`, __post_init__ must infer the embedding dimension by calling the embedder. It accepts only pathway.xpacks.llm.embedders.BaseEmbedder instances or pw.UDF callables; anything else (a plain function, a class, an OpenAI client wrapper without the UDF decorator) raises this TypeError from _get_embed_dimensions.","triggerScenarios":"Passing embedder=some_plain_function or a non-UDF object to UsearchKnnFactory/BruteForceKnnFactory without also passing dimensions; the check fires in __post_init__ when dimensions is None, i.e. at factory construction time.","commonSituations":"Using a raw sentence-transformers encode function or an SDK client method as the embedder instead of wrapping it with @pw.udf or using a BaseEmbedder from pathway.xpacks.llm; refactoring code so the embedder is lazily imported/wrapped and accidentally passing the unwrapped callable.","solutions":["Wrap the embedding function in a UDF: embedder=pw.udf(my_embed_fn) (async supported), so the isinstance(self.embedder, pw.UDF) branch matches.","Or use a ready BaseEmbedder from pathway.xpacks.llm.embedders (e.g. OpenAIEmbedder), which exposes get_embedding_dimension().","Or bypass inference entirely by passing dimensions=384 (etc.) explicitly so _get_embed_dimensions is never called."],"exampleFix":"# before\ndef embed(text: str) -> list[float]: ...\nfactory = UsearchKnnFactory(embedder=embed)\n\n# after\n@pw.udf\ndef embed(text: str) -> list[float]: ...\nfactory = UsearchKnnFactory(embedder=embed)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"import pathway as pw\nfrom pathway.xpacks.llm.embedders import BaseEmbedder\n\ndef is_valid_embedder(e) -> bool:\n    return isinstance(e, (BaseEmbedder, pw.UDF))","tryCatchPattern":"try:\n    factory = UsearchKnnFactory(embedder=embed)\nexcept TypeError as e:\n    if \"not a valid `pw.UDF`\" in str(e):\n        factory = UsearchKnnFactory(embedder=pw.udf(embed), dimensions=None)\n    else:\n        raise","preventionTips":["Always decorate embedding functions with @pw.udf at definition site.","Prefer BaseEmbedder implementations from pathway.xpacks.llm for known providers; they also give you get_embedding_dimension()."],"tags":["pathway","knn","embedder","udf","type-error"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}