{"record":{"id":"37e877cd6fe61e69","repo":"BerriAI/litellm","slug":"query-is-required-for-huggingface-rerank","errorCode":null,"errorMessage":"query is required for HuggingFace rerank","messagePattern":"query is required for HuggingFace rerank","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/huggingface/rerank/transformation.py","lineNumber":152,"sourceCode":"        }\n\n        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,","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/huggingface/rerank/transformation.py#L134-L170","documentation":"Raised by the HuggingFace rerank transformation when the translated rerank parameters lack a 'query' key. LiteLLM's huggingface rerank config expects the query/documents pair to have already been mapped to query/texts; a missing query aborts request building with a plain ValueError.","triggerScenarios":"Calling the HF rerank transformation directly (e.g. custom integration calling transform_rerank_request) without a query; or calling litellm.rerank(model='huggingface/...') with query=None/omitted.","commonSituations":"Building a generic rerank wrapper over multiple providers and forgetting that huggingface requires an explicit query; passing only documents.","solutions":["Always pass query: litellm.rerank(model='huggingface/BAAI/bge-reranker-base', query='...', documents=[...]).","If writing a provider-agnostic layer, validate query is a non-empty string before dispatch."],"exampleFix":"# before\nlitellm.rerank(model='huggingface/BAAI/bge-reranker-base', documents=docs)\n\n# after\nlitellm.rerank(model='huggingface/BAAI/bge-reranker-base', query='what is python?', documents=docs)","handlingStrategy":"validation","validationCode":"def validate_rerank_call(query: str | None, documents: list | None) -> None:\n    if not query or not isinstance(query, str):\n        raise ValueError('rerank requires a non-empty string query')\n    if not documents:\n        raise ValueError('rerank requires a non-empty documents list')","typeGuard":"def has_rerank_query(params: dict) -> bool:\n    q = params.get('query')\n    return isinstance(q, str) and len(q.strip()) > 0","tryCatchPattern":"try:\n    litellm.rerank(model=model, query=q, documents=docs)\nexcept ValueError as e:\n    if 'query is required' in str(e):\n        raise ValueError('caller bug: query missing in rerank dispatch') from e\n    raise","preventionTips":["Validate query+documents at your API boundary, not per provider","Type rerank wrappers with (query: str, documents: list[str]) signatures"],"tags":["huggingface","rerank","validation","missing-parameter"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}