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

Pass a non-empty documents list: litellm.rerank(model=..., query=..., documents=[...])

documents is required for DashScope rerank

Error message

documents is required for DashScope rerank

What it means

The sibling check to the query guard: transform_rerank_request also hard-requires 'documents' and raises ValueError('documents is required for DashScope rerank') when the params dict lacks it. Pure client-side validation — nothing was sent to DashScope.

Solutions

Pass a non-empty documents list: litellm.rerank(model=..., query=..., documents=[...])
Guard upstream: skip the rerank call entirely when retrieval returns zero documents instead of letting it fail
Check for key-name mismatches ('docs', 'passages') in forwarded kwargs

Example fix

# before
docs = retriever.search(q)  # returns []
litellm.rerank(model='dashscope/gte-rerank', query=q, documents=docs)  # ValueError (or would send nothing)

# after
docs = retriever.search(q)
if docs:
    litellm.rerank(model='dashscope/gte-rerank', query=q, documents=docs)
else:
    results = []  # short-circuit: nothing to rerank

Defensive patterns

Strategy: validation

Validate before calling

def should_rerank(query: str, docs: list) -> bool:
    return bool(isinstance(query, str) and query.strip() and isinstance(docs, list) and len(docs) > 0)

if should_rerank(query, retrieved):
    result = litellm.rerank(model='dashscope/gte-rerank', query=query, documents=retrieved)

Type guard

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

Try / catch

try:
    litellm.rerank(model='dashscope/gte-rerank', **params)
except ValueError as e:
    if 'documents is required' in str(e):
        return []  # nothing retrieved upstream - nothing to rerank
    raise

Prevention

Skip rerank when retrieval yields zero documents rather than letting the call fail
Enforce non-empty lists in your internal request schema, not at the provider boundary

When it happens

Trigger: litellm.rerank(model='dashscope/...', query='...') with documents omitted or None; retrieval step returned zero candidates and the caller forwarded an empty/absent documents value; kwargs-forwarding wrapper that swallows the documents field.

Common situations: RAG flow where the retriever found no chunks and code proceeds to rerank anyway; documents built conditionally and skipped on an empty branch; renaming from 'docs' or 'passages' during migration.

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/6f4a6d9c5ba8ba31. Report an issue: GitHub.

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