BerriAI/litellm · error · ValueError

query is required for DashScope rerank

Error message

query is required for DashScope rerank

What it means

transform_rerank_request builds the upstream DashScope /reranks body directly from the rerank parameters and hard-requires 'query'. If the params dict passed to it has no 'query' key it raises ValueError('query is required for DashScope rerank') before any network I/O — the request was structurally incomplete.

Solutions

  1. Pass the query explicitly: litellm.rerank(model=..., query='...', documents=[...])
  2. If building calls dynamically, assert 'query' exists and is a non-empty string before invoking rerank
  3. Check for key-name mismatches ('q', 'question', 'search') in whatever dict/kwargs you forward

Example fix

# before
litellm.rerank(model='dashscope/gte-rerank', documents=['a', 'b'])  # ValueError: query is required

# after
litellm.rerank(
    model='dashscope/gte-rerank',
    query='which item is the letter a?',
    documents=['a', 'b'],
)
Defensive patterns

Strategy: validation

Validate before calling

def validate_rerank_call(query, documents) -> None:
    if not isinstance(query, str) or not query.strip():
        raise ValueError('rerank requires a non-empty query string')
    if not isinstance(documents, list) or not documents:
        raise ValueError('rerank requires a non-empty documents list')

Type guard

def has_valid_query(params: dict) -> bool:
    q = params.get('query')
    return isinstance(q, str) and bool(q.strip())

Try / catch

try:
    litellm.rerank(model='dashscope/gte-rerank', **params)
except ValueError as e:
    if 'query is required' in str(e):
        return skip_with_warning('rerank skipped: no query')
    raise

Prevention

When it happens

Trigger: litellm.rerank(model='dashscope/...', documents=[...]) with query omitted or dropped (None); dynamically-built params where the query field is missing; ported Cohere-style code where the query key got lost; passing query under a different key name ('q', 'question').

Common situations: Search/RAG pipelines assembling rerank calls from user input where the query can be empty; wrapper functions with optional query that forward **kwargs directly; schema drift between your internal API and litellm.rerank's parameters.

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 BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/2baf65b699ac7eab. Report an issue: GitHub.

Appendix: 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 77b7c6c40c)