BerriAI/litellm · error · ValueError

query is required for DashScope rerank

Error message

query is required for DashScope rerank

What it means

The DashScope rerank request transformer requires a 'query' field; if the optional rerank params dict passed to transform_rerank_request lacks 'query', a ValueError is raised before any HTTP call. This typically means the caller invoked the rerank API without a query argument.

Source

Thrown at litellm/llms/dashscope/rerank/transformation.py:141

        params: Final[OptionalRerankParams] = OptionalRerankParams(
            query=query,
            documents=documents,
        )
        if top_n is not None:
            params["top_n"] = top_n
        if return_documents is not None:
            params["return_documents"] = return_documents
        return dict(params)

    def transform_rerank_request(
        self,
        model: str,
        optional_rerank_params: dict,
        headers: dict,
        litellm_params: dict | None = None,
    ) -> dict:
        if "query" not in optional_rerank_params:
            raise ValueError("query is required for DashScope rerank")
        if "documents" not in optional_rerank_params:
            raise ValueError("documents is required for DashScope rerank")

        request: Final[dict[str, Any]] = {
            "model": model,
            "query": optional_rerank_params["query"],
            "documents": optional_rerank_params["documents"],
        }
        if optional_rerank_params.get("top_n") is not None:
            request["top_n"] = optional_rerank_params["top_n"]
        if optional_rerank_params.get("return_documents") is not None:
            request["return_documents"] = optional_rerank_params["return_documents"]
        return request

    def transform_rerank_response(
        self,
        model: str,
        raw_response: httpx.Response,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass a non-empty query: litellm.rerank(model=..., query="search text", documents=[...])
2. If query is empty in your app, guard upstream and skip/short-circuit the rerank call
3. Check any dynamic dict construction that builds rerank params to ensure 'query' survives

Example fix

# before
resp = litellm.rerank(model="dashscope/gte-rerank", documents=chunks)

# after
resp = litellm.rerank(model="dashscope/gte-rerank", query=user_question, documents=chunks)

if not query or not str(query).strip():
    raise ValueError("rerank requires a non-empty query")

def is_valid_rerank_request(params: dict) -> bool:
    return isinstance(params.get("query"), str) and bool(params["query"].strip()) and isinstance(params.get("documents"), list)

try:
    resp = litellm.rerank(model=m, query=q, documents=docs)
except ValueError as e:
    if "query is required" in str(e):
        return docs  # graceful degrade: skip reranking
    raise

When it happens

Trigger: Calling litellm.rerank(model="dashscope/...", documents=[...]) with no query= argument, or constructing a rerank request via the lower-level transformer without 'query' in the params dict.

Common situations: Adapting code from a Cohere-style SDK call where query was optional or named differently; building the request dict dynamically and the query key is dropped when the search box is empty.

Related errors

• documents is required for DashScope rerank
• No results found in the response={response}
• DashScope API key is required. Set 'DASHSCOPE_API_KEY' env v
• raw_response.text (upstream DashScope error body)
• response_json.get("message", str(response_json)) (upstream D

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/2baf65b699ac7eab. Report an issue: GitHub.