What causes "documents is required for DashScope rerank" in BerriAI/litellm?

Pass documents explicitly: litellm.rerank(model=..., query=q, documents=["text1", "text2"])

BerriAI/litellm · error · ValueError

documents is required for DashScope rerank

Error message

documents is required for DashScope rerank

What it means

The DashScope rerank request transformer requires a 'documents' list; if the optional rerank params lack 'documents', a ValueError is raised before any network request. Rerank without candidate documents is meaningless, so the transformer refuses to build the request.

Source

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

            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,
        model_response: RerankResponse,
        logging_obj: LiteLLMLoggingObj,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass documents explicitly: litellm.rerank(model=..., query=q, documents=["text1", "text2"])
Guard in the retrieval pipeline: skip rerank when the retrieved chunk list is empty
Verify the key name is exactly 'documents' (not 'docs', 'passages', 'texts')

Example fix

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

# after
resp = litellm.rerank(model="dashscope/gte-rerank", query=q, documents=[c["text"] for c in retrieved])

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(documents, list) or len(documents) == 0:
    # nothing to rerank
    return []  # or skip the call entirely

Type guard

def has_rerank_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 / catch

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

Prevention

Short-circuit the pipeline when retrieval returns zero chunks
Use keyword-only parameters (def rerank(*, query, documents)) in your wrapper so omission fails at call time

When it happens

Trigger: Calling litellm.rerank(model="dashscope/...", query="...") without documents, or passing an empty/missing documents key through dynamic param construction.

Common situations: RAG retrieval step returned zero chunks and the pipeline still calls rerank; a variable named 'docs' vs 'documents' mismatch when assembling kwargs.

Related errors

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