lancedb/lancedb · error · ValueError

The query used for vector search is not a…

Error message

                The query used for vector search is not a string.
                In this case, the reranker query needs to be specified explicitly.

What it means

When a reranker is attached to a LanceVectorQueryBuilder whose query is a vector (not a string), the reranker needs the original text to rerank against. If neither the vector query carried a string (self._str_query is None) nor an explicit query_string was passed, rerank() raises this ValueError. Rerankers like cross-encoders operate on text and cannot derive it from the embedding vector.

Solutions

Pass the text explicitly: .rerank(reranker, query_string="your query text").
Perform a hybrid query (query_type="hybrid") so .text() sets self._str_query before reranking.
Skip the reranker for pure vector queries or use a reranker that does not need the query string.
Wrap rerank in try/except ValueError and fall back to unranked results.

Example fix

// before
tbl.search([0.1, 0.2]).rerank(Reranker())

// after
tbl.search([0.1, 0.2]).rerank(Reranker(), query_string="find the docs about cats")

Defensive patterns

Strategy: try-catch

Validate before calling

def can_rerank(q, reranker, query_string=None) -> bool:
    str_query = getattr(q, "_str_query", None)
    return str_query is not None or isinstance(query_string, str)

Type guard

def has_query_text(q) -> bool:
    return getattr(q, "_str_query", None) is not None

Try / catch

try:
    q = q.rerank(reranker)
except ValueError as e:
    if "query needs to be specified explicitly" in str(e):
        q = q.rerank(reranker, query_string=user_text)
    else:
        raise

Prevention

When reranking pure vector searches, always pass query_string=... with the original text.
Prefer hybrid queries so .text() supplies the string the reranker needs.
Check whether the chosen reranker requires query text before enabling it.

When it happens

Trigger: table.search(vector).rerank(reranker) where the vector search has no associated text and no query_string argument is supplied; hybrid builders where text() was never called.

Common situations: Pure vector searches with a cross-encoder/RRF-style reranker that requires text; pipelines that add rerankers unconditionally; forgetting to pass query_string= after searching by raw embedding.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of lancedb/lancedb@c7b051aff7 (2026-09-08). Data as JSON: /api/errors/caa2a3dbf5e54294. Report an issue: GitHub.

Appendix: source

Thrown at python/python/lancedb/query.py:1954

        reranker: Reranker
            The reranker to use.

        query_string: Optional[str]
            The query to use for reranking. This needs to be specified explicitly here
            as the query used for vector search may already be vectorized and the
            reranker requires a string query.
            This is only required if the query used for vector search is not a string.
            Note: This doesn't yet support the case where the query is multimodal or a
            list of vectors.

        Returns
        -------
        LanceVectorQueryBuilder
            The LanceQueryBuilder object.
        """
        self._reranker = reranker
        if self._str_query is None and query_string is None:
            raise ValueError(
                """
                The query used for vector search is not a string.
                In this case, the reranker query needs to be specified explicitly.
                """
            )
        if query_string is not None and not isinstance(query_string, str):
            raise ValueError("Reranking currently only supports string queries")
        self._str_query = query_string if query_string is not None else self._str_query
        if reranker.score == "all":
            self.with_row_id(True)
        return self

    def bypass_vector_index(self) -> LanceVectorQueryBuilder:
        """
        If this is called then any vector index is skipped

        An exhaustive (flat) search will be performed.  The query vector will
        be compared to every vector in the table.  At high scales this can be

View on GitHub (pinned to c7b051aff7)