pathwaycom/pathway · error · ValueError

HybridIndex requires at least two indices to be provided dur

Error message

HybridIndex requires at least two indices to be provided during initialization

What it means

HybridIndex combines multiple retrieval indices using Reciprocal Rank Fusion: each index is queried and each retrieved row gets score 1/(k+rank) summed over all indices. Combining requires at least two constituent retrievers — a single one adds nothing over using it directly. The constructor therefore raises ValueError when retrievers has fewer than two entries (including an empty list).

Source

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

from pathway.stdlib.indexing.retrievers import InnerIndexFactory


class HybridIndex(InnerIndex):
    """
    Hybrid Index that composes any number of other indices and combines them using
    the Reciprocal Rank Fusion (RRF). It queries each index, and each retrieved row ``d`` is assigned
    score ``1/(k+rank(d))``, which is then summed over all indices. ``HybridIndex`` returns
    best rows from indexed data according to this score.

    Args:
        retrievers: list of indices to be used to compose the hybrid index.
        k: constant used for calculating ranking score.

    """

    def __init__(self, retrievers: list[InnerIndex], k: float = 60):
        if len(retrievers) < 2:
            raise ValueError(
                "HybridIndex requires at least two indices to be provided during initialization"
            )
        self.retrievers = retrievers
        self.k = k

    def _combine_results(
        self,
        query_retriever: Callable[[InnerIndex], pw.Table],
        query_table: pw.Table,
        number_of_matches: pw.ColumnExpression | int,
        *,
        as_of_now: bool,
    ) -> pw.Table:
        @pw.udf(deterministic=True)
        def enumerate_results(
            results: list[tuple[pw.Pointer, float]]
        ) -> list[tuple[int, pw.Pointer]]:
            return [(i, x[0]) for i, x in enumerate(results, start=1)]

View on GitHub (pinned to fa2f74a464)

Solutions

Pass at least two index objects, e.g. HybridIndex(retrievers=[bm25_index, knn_index]).
If only one retriever is available, skip HybridIndex entirely and use that retriever directly.
Validate the retriever list length against config before building the hybrid index and fail with a config-level message.

Example fix

# before
retrievers = [knn_index]  # bm25 disabled in config
index = HybridIndex(retrievers=retrievers)

# after
retrievers = [knn_index, bm25_index]
index = HybridIndex(retrievers=retrievers)
# or, with a single retriever:
index = knn_index

Defensive patterns

Strategy: validation

Validate before calling

def build_hybrid(retrievers, k=60):
    if len(retrievers) >= 2:
        return HybridIndex(retrievers=retrievers, k=k)
    if len(retrievers) == 1:
        return retrievers[0]
    raise ValueError("no retrievers configured")

Prevention

Validate retriever lists from config at load time: assert 2+ enabled retrievers or fall back to the single retriever directly.
Warn (not just error) when a config leaves exactly one retriever enabled, since it usually signals a misconfiguration.

When it happens

Trigger: Instantiating HybridIndex(retrievers=[single_index]) or HybridIndex(retrievers=[]); commonly when the retriever list is built dynamically from config (e.g. enabled retrievers in an RAG pipeline config) and only one ends up enabled.

Common situations: A configurable RAG setup where users toggle retrievers on/off in a YAML config and disable all but one; a list built by appending conditionally where a condition silently filters everything; refactoring from two hard-coded indices to a dynamic list.

Related errors

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