BerriAI/litellm · error · ValueError

query is required for Fireworks AI rerank

Error message

query is required for Fireworks AI rerank

What it means

transform_rerank_request() enforces the Fireworks rerank API contract before building the payload: a 'query' key must exist in optional_rerank_params. Rerank ranks documents against a query, so a request without one cannot be translated and is rejected client-side with this ValueError.

Source

Thrown at litellm/llms/fireworks_ai/rerank/transformation.py:135

        # If 'Authorization' is provided in headers, it overrides the default.
        if "Authorization" in headers:
            default_headers["Authorization"] = headers["Authorization"]

        # Merge other headers, overriding any default ones except Authorization
        return {**default_headers, **headers}

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

        # Handle model name - Fireworks AI expects model name like "fireworks/qwen3-reranker-8b"
        # Remove fireworks_ai/ prefix if present
        if model.startswith("fireworks_ai/"):
            model = model.replace("fireworks_ai/", "")

        # If model doesn't start with "fireworks/", add it
        # But don't add if it already has the prefix
        if not model.startswith("fireworks/"):
            model = f"fireworks/{model}"

        request_data: Final = {
            "model": model,
            "query": optional_rerank_params["query"],
            "documents": optional_rerank_params["documents"],
        }

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass query as a positional/keyword argument: litellm.rerank(model=..., query='...', documents=[...]).
2. If kwargs are built dynamically, validate the dict contains both 'query' and 'documents' (truthy query) before calling rerank.
3. Check for typos or renaming from another SDK's parameter name (q, search_query, text) to litellm's 'query'.

Example fix

# before
results = litellm.rerank(model="fireworks_ai/fireworks/qwen3-reranker-8b", documents=["doc1", "doc2"])

# after
results = litellm.rerank(model="fireworks_ai/fireworks/qwen3-reranker-8b", query="find doc1", documents=["doc1", "doc2"])

def safe_rerank_kwargs(model: str, query: str | None, documents: list[str]) -> dict:
    if not query:
        raise ValueError("Cannot rerank without a non-empty query")
    if not documents:
        raise ValueError("Cannot rerank without documents")
    return {"model": model, "query": query, "documents": documents}

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

try:
    litellm.rerank(**params)
except ValueError as e:
    if "query is required" in str(e):
        # degrade gracefully: fall back to original document order
        return list(range(len(params.get("documents", []))))
    raise

When it happens

Trigger: Calling litellm.rerank() with documents (and model/api_key) but omitting query, e.g. litellm.rerank(model='fireworks_ai/...', documents=['a','b']).

Common situations: Porting code from a search/embedding API that takes only documents; dynamically built kwargs where the query variable is None or the key is typo'd (e.g. 'search_query'); the query is computed from user input and came back empty/missing in an edge case.

Related errors

• documents is required for Fireworks AI rerank
• Missing required fields in the result={result}
• Missing model or messages
• No results found in the response={response}
• query is required for DashScope rerank

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