BerriAI/litellm · error · ValueError

documents is required for Fireworks AI rerank

Error message

documents is required for Fireworks AI rerank

What it means

The second half of the rerank request contract check: transform_rerank_request() requires a 'documents' list alongside 'query'. Without documents there is nothing to rank, so the transformation raises this ValueError before any HTTP request is sent.

Source

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

            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"],
        }

        if "top_n" in optional_rerank_params and optional_rerank_params["top_n"] is not None:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Include documents as a list of strings: litellm.rerank(model=..., query=..., documents=['a', 'b']).
2. Guard upstream: skip or short-circuit the rerank call when the retrieved document list is empty.
3. Verify the exact key name 'documents' in dynamically built kwargs (not 'docs', 'texts', 'inputs').

Example fix

# before
results = litellm.rerank(model="fireworks_ai/fireworks/qwen3-reranker-8b", query="find doc1")

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

def rerank_or_none(model: str, query: str, documents: list[str] | None):
    if not documents:  # nothing to rank; skip the API call entirely
        return None
    return litellm.rerank(model=model, query=query, documents=documents)

def has_documents(params: dict) -> bool:
    docs = params.get("documents")
    return isinstance(docs, list) and len(docs) > 0 and all(isinstance(d, str) for d in docs)

try:
    litellm.rerank(**params)
except ValueError as e:
    if "documents is required" in str(e):
        return []  # retrieval returned nothing upstream
    raise

When it happens

Trigger: Calling litellm.rerank(model='fireworks_ai/...', query='...') with documents omitted, set to an empty dict, or under a misspelled key like 'docs' or 'texts'.

Common situations: Upstream retrieval step returned no items and the caller forwarded kwargs anyway; parameter renamed when migrating from Cohere's rerank API; dynamically constructed optional params where the documents branch never executes.

Related errors

• query 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/5211f83e2746b09a. Report an issue: GitHub.