{"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/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/hosted_vllm/rerank/transformation.py#L119-L155","documentation":"Raised by HostedVLLM RerankConfig.transform_rerank_request when the optional_rerank_params dict lacks a 'documents' key. The vLLM rerank endpoint needs the list of documents to score, so LiteLLM refuses to build the request payload without it.","triggerScenarios":"Calling litellm.rerank(model='hosted_vllm/...', query='...') with no documents; forwarding a dynamically built params dict where documents failed to populate (empty retrieval results path that still calls rerank, key named 'docs' instead of 'documents').","commonSituations":"RAG pipeline where the retrieval step returned nothing and the rerank step still runs; renaming variables during refactor (docs vs documents); wrapper that conditionally includes documents only when non-empty (note: an empty list [] would pass this check but fail server-side — omitting the key is what raises).","solutions":["Always pass documents: litellm.rerank(model='hosted_vllm/...', query=q, documents=docs, api_base=...).","Short-circuit in RAG flows: skip rerank entirely when retrieval returns no documents instead of calling it without the key.","Validate dynamic param dicts before the call: required = {'query','documents'}; missing = required - params.keys()."],"exampleFix":"# before\nlitellm.rerank(model='hosted_vllm/bge-reranker-v2-m3', query=q, api_base=base)\n# raises ValueError: documents is required for Hosted VLLM rerank\n\n# after\nif retrieved_docs:\n    litellm.rerank(model='hosted_vllm/bge-reranker-v2-m3', query=q,\n                   documents=retrieved_docs, api_base=base)\n","handlingStrategy":"validation","validationCode":"def validate_rerank_request(params: dict) -> None:\n    for key in (\"query\", \"documents\"):\n        if key not in params:\n            raise ValueError(f\"'{key}' is required for hosted_vllm rerank\")\n\ndef maybe_rerank(params: dict) -> dict | None:\n    if not params.get(\"documents\"):\n        return None  # skip rerank when retrieval was empty\n    validate_rerank_request(params)\n    return params","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Short-circuit RAG rerank steps when the retrieval stage produced no documents.","Validate dynamic param dicts against {'query','documents'} before the litellm call."],"tags":["hosted-vllm","rerank","validation","required-params"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}