BerriAI/litellm · error · ValueError

Cohere 'documents' param is required for HuggingFace rerank

Error message

Cohere 'documents' param is required for HuggingFace rerank

What it means

Raised by the HuggingFace rerank transformation when 'texts' is absent from the rerank params. The message mentions Cohere's 'documents' param because litellm's rerank API is Cohere-shaped: documents must be supplied (and mapped to 'texts' for the HF API). Its absence means no candidate documents to score.

Source

Thrown at litellm/llms/huggingface/rerank/transformation.py:154

        if api_key:
            default_headers["Authorization"] = f"Bearer {api_key}"

        if "Authorization" in headers:
            default_headers["Authorization"] = headers["Authorization"]

        return {**default_headers, **headers}

    def transform_rerank_request(
        self,
        model: str,
        optional_rerank_params: OptionalRerankParams | dict,
        headers: dict,
        litellm_params: dict | None = None,
    ) -> dict:
        if "query" not in optional_rerank_params:
            raise ValueError("query is required for HuggingFace rerank")
        if "texts" not in optional_rerank_params:
            raise ValueError("Cohere 'documents' param is required for HuggingFace rerank")
        # Ensure return_text is a boolean value
        # HuggingFace API expects return_text parameter, corresponding to our return_documents parameter
        request_body: Final = {
            "raw_scores": False,
            "truncate": False,
            "truncation_direction": "Right",
        }

        request_body.update(optional_rerank_params)

        return request_body

    def transform_rerank_response(
        self,
        model: str,
        raw_response: httpx.Response,
        model_response: RerankResponse,
        logging_obj: LoggingClass,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass a non-empty documents list alongside query.
Guard upstream: skip the rerank stage when retrieved candidates is empty.
If integrating at the transformation layer, map documents=[...] to texts=[...] before calling.

Example fix

# before
candidates = retriever.search(q, k=0)  # empty
litellm.rerank(model='hf-reranker/BAAI/bge-reranker-base', query=q, documents=candidates)

# after
candidates = retriever.search(q, k=10)
if not candidates:
    return []
litellm.rerank(model='hf-reranker/BAAI/bge-reranker-base', query=q, documents=candidates)

Defensive patterns

Strategy: validation

Validate before calling

def validate_rerank_documents(documents: list[str] | None) -> list[str]:
    if not documents:
        raise ValueError('documents must be a non-empty list of strings')
    if not all(isinstance(d, str) and d for d in documents):
        raise ValueError('all documents must be non-empty strings')
    return documents

Prevention

Skip rerank stage when retrieval returns zero candidates
Enforce non-empty documents in shared rerank helper used by all providers

When it happens

Trigger: Calling rerank with query set but documents omitted/empty, or invoking transform_rerank_request directly with params that never went through the documents->texts mapping.

Common situations: A retrieval pipeline where the candidate set was empty after top-k filtering, so documents never reaches the rerank call.

Related errors

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