pathwaycom/pathway · error · ValueError

HybridIndexFactory requires at least two retriever factories

Q: What causes "HybridIndexFactory requires at least two retriever factories to be provided during initialization" in pathwaycom/pathway?

Provide at least two factories, e.g. HybridIndexFactory(retriever_factories=[UsearchKnnFactory(...), TantivyBM25Factory(...)]).

Error message

HybridIndexFactory requires at least two retriever factories to be provided during initialization

What it means

HybridIndexFactory is the declarative counterpart of HybridIndex: it takes a list of InnerIndexFactory objects and builds a HybridIndex from the indices they produce. Reciprocal Rank Fusion over fewer than two retriever factories is meaningless, so the constructor raises ValueError when retriever_factories has length < 2, mirroring the HybridIndex check.

Source

Thrown at python/pathway/stdlib/indexing/hybrid_index.py:172

            )

        return self._combine_results(
            query_retriever, query_column.table, number_of_matches, as_of_now=True
        )


class HybridIndexFactory(InnerIndexFactory):
    """
    Factory for creating hybrid indices.

    Args:
        retriever_factories: list of factories of indices that will be used in the hybrid index
        k: constant used for calculating ranking score.
    """

    def __init__(self, retriever_factories: list[InnerIndexFactory], k: float = 60):
        if len(retriever_factories) < 2:
            raise ValueError(
                "HybridIndexFactory requires at least two retriever factories to be provided during initialization"
            )
        self.retriever_factories = retriever_factories
        self.k = k

    def build_inner_index(
        self,
        data_column: pw.ColumnReference,
        metadata_column: pw.ColumnExpression | None = None,
    ) -> InnerIndex:
        retrievers = [
            retriever_factory.build_inner_index(data_column, metadata_column)
            for retriever_factory in self.retriever_factories
        ]
        hybrid_index = HybridIndex(retrievers, self.k)
        return hybrid_index

View on GitHub (pinned to fa2f74a464)

Solutions

Provide at least two factories, e.g. HybridIndexFactory(retriever_factories=[UsearchKnnFactory(...), TantivyBM25Factory(...)]).
If only one retriever type is wanted, use that factory directly instead of wrapping it in HybridIndexFactory.
Add a startup assertion len(retriever_factories) >= 2 in the config-loading code with a clear config error message.

Example fix

# before
factory = HybridIndexFactory(retriever_factories=[UsearchKnnFactory(dimensions=384)])

# after
factory = HybridIndexFactory(retriever_factories=[
    UsearchKnnFactory(dimensions=384),
    TantivyBM25Factory(),
])

Defensive patterns

Strategy: validation

Validate before calling

def build_hybrid_factory(factories, k=60):
    if len(factories) >= 2:
        return HybridIndexFactory(retriever_factories=factories, k=k)
    if len(factories) == 1:
        return factories[0]
    raise ValueError("no retriever factories configured")

Prevention

Treat factory lists parsed from user config as untrusted input: validate length and element types before constructing Pathway objects.
Keep a single config schema validator that runs at startup and reports all such misconfigurations at once.

When it happens

Trigger: Constructing HybridIndexFactory(retriever_factories=[f]) or with an empty list — typically when the factory list comes from user configuration (which embedders/retrievers are enabled) and only one survives filtering.

Common situations: Declarative RAG pipelines (pw.xpacks.llm) assembling factories from a config file where one retriever is disabled; conditionally appending factories with a bug that skips all but one; passing a single factory while prototyping.

Related errors

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/c574a6fa762c3ca7. Report an issue: GitHub.