{"record":{"id":"2d2050cea31c8645","repo":"BerriAI/litellm","slug":"cohere-documents-param-is-required-for-huggingfa","errorCode":null,"errorMessage":"Cohere 'documents' param is required for HuggingFace rerank","messagePattern":"Cohere 'documents' param is required for HuggingFace rerank","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/huggingface/rerank/transformation.py","lineNumber":154,"sourceCode":"        if api_key:\n            default_headers[\"Authorization\"] = f\"Bearer {api_key}\"\n\n        if \"Authorization\" in headers:\n            default_headers[\"Authorization\"] = headers[\"Authorization\"]\n\n        return {**default_headers, **headers}\n\n    def transform_rerank_request(\n        self,\n        model: str,\n        optional_rerank_params: OptionalRerankParams | dict,\n        headers: dict,\n        litellm_params: dict | None = None,\n    ) -> dict:\n        if \"query\" not in optional_rerank_params:\n            raise ValueError(\"query is required for HuggingFace rerank\")\n        if \"texts\" not in optional_rerank_params:\n            raise ValueError(\"Cohere 'documents' param is required for HuggingFace rerank\")\n        # Ensure return_text is a boolean value\n        # HuggingFace API expects return_text parameter, corresponding to our return_documents parameter\n        request_body: Final = {\n            \"raw_scores\": False,\n            \"truncate\": False,\n            \"truncation_direction\": \"Right\",\n        }\n\n        request_body.update(optional_rerank_params)\n\n        return request_body\n\n    def transform_rerank_response(\n        self,\n        model: str,\n        raw_response: httpx.Response,\n        model_response: RerankResponse,\n        logging_obj: LoggingClass,","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/huggingface/rerank/transformation.py#L136-L172","documentation":"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.","triggerScenarios":"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.","commonSituations":"A retrieval pipeline where the candidate set was empty after top-k filtering, so documents never reaches the rerank call.","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."],"exampleFix":"# before\ncandidates = retriever.search(q, k=0)  # empty\nlitellm.rerank(model='hf-reranker/BAAI/bge-reranker-base', query=q, documents=candidates)\n\n# after\ncandidates = retriever.search(q, k=10)\nif not candidates:\n    return []\nlitellm.rerank(model='hf-reranker/BAAI/bge-reranker-base', query=q, documents=candidates)","handlingStrategy":"validation","validationCode":"def validate_rerank_documents(documents: list[str] | None) -> list[str]:\n    if not documents:\n        raise ValueError('documents must be a non-empty list of strings')\n    if not all(isinstance(d, str) and d for d in documents):\n        raise ValueError('all documents must be non-empty strings')\n    return documents","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Skip rerank stage when retrieval returns zero candidates","Enforce non-empty documents in shared rerank helper used by all providers"],"tags":["huggingface","rerank","validation","missing-parameter"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}