{"record":{"id":"1177b6f9d5296b10","repo":"BerriAI/litellm","slug":"query-is-required-for-hosted-vllm-rerank","errorCode":null,"errorMessage":"query is required for Hosted VLLM rerank","messagePattern":"query is required for Hosted VLLM rerank","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/hosted_vllm/rerank/transformation.py","lineNumber":135,"sourceCode":"            \"content-type\": \"application/json\",\n        }\n\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,","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/hosted_vllm/rerank/transformation.py#L117-L153","documentation":"Raised by HostedVLLM RerankConfig.transform_rerank_request when the optional_rerank_params dict passed to the rerank call does not contain a 'query' key. The vLLM rerank endpoint requires a query to score documents against, so LiteLLM fails fast before building the RerankRequest payload.","triggerScenarios":"Calling litellm.rerank(model='hosted_vllm/...', documents=docs) without query=; or constructing the call dynamically from a dict that may omit 'query' (e.g. **params where params lacks the key). Note litellm.rerank's own signature normally enforces query, so this is most often hit via programmatic param dicts or wrapper layers.","commonSituations":"Generic retrieval wrapper that forwards an optional params dict; refactoring left query out of a call site; default/fallback code path that reranks 'documents only' (not valid for vLLM rerank).","solutions":["Always pass query: litellm.rerank(model='hosted_vllm/...', query='...', documents=[...], api_base=...).","When building params dynamically, validate required keys before the call: assert {'query','documents'} <= params.keys().","If the query is genuinely absent in your flow, you need one — rerank scores documents relative to a query, so design the caller to always supply it."],"exampleFix":"# before\nparams = {'documents': docs}  # query missing\nlitellm.rerank(model='hosted_vllm/bge-reranker-v2-m3', api_base=base, **params)\n# raises ValueError: query is required for Hosted VLLM rerank\n\n# after\nparams = {'query': user_question, 'documents': docs}\nlitellm.rerank(model='hosted_vllm/bge-reranker-v2-m3', api_base=base, **params)\n","handlingStrategy":"validation","validationCode":"REQUIRED_RERANK_KEYS = {\"query\", \"documents\"}\n\ndef validate_rerank_params(params: dict) -> None:\n    missing = REQUIRED_RERANK_KEYS - params.keys()\n    if missing:\n        raise ValueError(f\"rerank call missing required keys: {sorted(missing)}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When building the rerank call from a dynamic dict, assert required keys before calling litellm.","Let your type checker help: call litellm.rerank with keyword args (query=, documents=) instead of **params splats."],"tags":["hosted-vllm","rerank","validation","required-params"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}