{"record":{"id":"b7d8a11ca873fef6","repo":"BerriAI/litellm","slug":"documents-is-required-for-hosted-vllm-rerank","errorCode":null,"errorMessage":"documents is required for Hosted VLLM rerank","messagePattern":"documents is required for Hosted VLLM rerank","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/hosted_vllm/rerank/transformation.py","lineNumber":137,"sourceCode":"\n        # If 'Authorization' is provided in headers, it overrides the default.\n        if \"Authorization\" in headers:\n            default_headers[\"Authorization\"] = headers[\"Authorization\"]\n\n        # Merge other headers, overriding any default ones except Authorization\n        return {**default_headers, **headers}\n\n    def transform_rerank_request(\n        self,\n        model: str,\n        optional_rerank_params: 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 Hosted VLLM rerank\")\n        if \"documents\" not in optional_rerank_params:\n            raise ValueError(\"documents is required for Hosted VLLM rerank\")\n\n        rerank_request: Final = RerankRequest(\n            model=model,\n            query=optional_rerank_params[\"query\"],\n            documents=optional_rerank_params[\"documents\"],\n            top_n=optional_rerank_params.get(\"top_n\", None),\n            rank_fields=optional_rerank_params.get(\"rank_fields\", None),\n            return_documents=optional_rerank_params.get(\"return_documents\", None),\n            instruction=optional_rerank_params.get(\"instruction\", None),\n        )\n        return rerank_request.model_dump(exclude_none=True)\n\n    def transform_rerank_response(\n        self,\n        model: str,\n        raw_response: httpx.Response,\n        model_response: RerankResponse,\n        logging_obj: LiteLLMLoggingObj,","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/llms/hosted_vllm/rerank/transformation.py#L119-L155","documentation":"transform_rerank_request() also validates that the rerank payload contains 'documents' (the list of strings to be scored against the query). vLLM's /rerank endpoint requires both query and documents, so a missing documents key raises ValueError client-side before the HTTP request. The value is forwarded into a RerankRequest pydantic model alongside top_n, rank_fields, return_documents, and instruction.","triggerScenarios":"litellm.rerank(model='hosted_vllm/...', query='...') with no documents kwarg; passing an empty/None documents value that a wrapper strips before the call; confusing rerank (score existing docs) with completion generation.","commonSituations":"Refactoring retrieval code where documents were fetched conditionally and the list ended up absent; passing documents under a different kwarg (docs=, texts=); calling rerank as a similarity check without supplying the corpus.","solutions":["Pass the list to rank: litellm.rerank(model=..., api_base=..., query='...', documents=['doc1', 'doc2'])","Assert documents is a non-empty list before calling","Check wrappers for keys named docs/texts instead of documents","Return early in retrieval pipelines when the candidate set is empty rather than calling rerank"],"exampleFix":"# before\nlitellm.rerank(model=\"hosted_vllm/jina-reranker\", api_base=base, query=\"find a\")\n\n# after\nlitellm.rerank(model=\"hosted_vllm/jina-reranker\", api_base=base, query=\"find a\", documents=[\"a\", \"b\"])","handlingStrategy":"validation","validationCode":"if not documents:\n    raise ValueError(\"rerank requires a non-empty documents list\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Short-circuit retrieval when the candidate set is empty — there is nothing to rank","Use the exact kwarg name documents (not docs/texts) in wrappers","Type retrieval inputs as (query: str, documents: list[str]) so missing data is a type error, not a runtime surprise"],"tags":["hosted-vllm","rerank","missing-argument","request-validation","litellm"],"backgroundTag":"missing-required-argument","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}