BerriAI/litellm · error · ValueError

documents is required for Vertex AI rerank

Error message

documents is required for Vertex AI rerank

What it means

ValueError raised in transform_rerank_request when 'documents' is missing from the rerank parameters. Documents (a list of strings or of dicts with id/content) are the payload being ranked; without them there is nothing to send to the Discovery Engine rank endpoint.

Source

Thrown at litellm/llms/vertex_ai/rerank/transformation.py:119

            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 the request from Cohere format to Vertex AI Discovery Engine format
        """
        if "query" not in optional_rerank_params:
            raise ValueError("query is required for Vertex AI rerank")
        if "documents" not in optional_rerank_params:
            raise ValueError("documents is required for Vertex AI rerank")

        query: Final = optional_rerank_params["query"]
        documents: Final = optional_rerank_params["documents"]
        top_n: Final = optional_rerank_params.get("top_n", None)
        return_documents: Final = optional_rerank_params.get("return_documents", True)

        # Convert documents to records format
        records: Final = []
        for idx, document in enumerate(documents):
            if isinstance(document, str):
                content = document
                title = " ".join(document.split()[:3])  # First 3 words as title
            else:
                # Handle dict format
                content = document.get("text", str(document))
                title = document.get("title", " ".join(content.split()[:3]))

            records.append({"id": str(idx), "title": title, "content": content})

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass documents=[...] - a list of strings or of dicts
2. Verify the exact key name is 'documents'
3. Guard with a pre-call check (see defense)

Example fix

# before
litellm.rerank(model='vertex_ai/semantic-ranker', query='q')

# after
litellm.rerank(
    model='vertex_ai/semantic-ranker',
    query='q',
    documents=['doc one text', 'doc two text'],
)

def valid_rerank_documents(params: dict) -> bool:
    docs = params.get('documents')
    return isinstance(docs, list) and len(docs) > 0

def is_rerank_request(value: dict) -> bool:
    docs = value.get('documents') if isinstance(value, dict) else None
    return (
        isinstance(docs, list)
        and len(docs) > 0
        and all(isinstance(d, (str, dict)) for d in docs)
    )

try:
    resp = litellm.rerank(model=model, **params)
except ValueError as e:
    if 'documents is required' in str(e):
        raise SystemExit('Missing rerank documents')
    raise

When it happens

Trigger: Calling litellm.rerank with only a query; the documents key misspelled ('docs', 'texts'); documents passed as a positional argument the handler does not read.

Common situations: Dynamic param construction dropping empty lists; schema drift from other rerank providers; thin wrappers that forward the wrong field names.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• query is required for Vertex AI rerank
• Gemini image edit requires at least one image.
• Either 'model' or 'agent' must be provided
• query is required for Hosted VLLM rerank
• documents is required for Hosted VLLM rerank

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/373a01e8b8c20c63. Report an issue: GitHub.