{"record":{"id":"6f4a6d9c5ba8ba31","repo":"BerriAI/litellm","slug":"documents-is-required-for-dashscope-rerank","errorCode":null,"errorMessage":"documents is required for DashScope rerank","messagePattern":"documents is required for DashScope rerank","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/dashscope/rerank/transformation.py","lineNumber":143,"sourceCode":"            documents=documents,\n        )\n        if top_n is not None:\n            params[\"top_n\"] = top_n\n        if return_documents is not None:\n            params[\"return_documents\"] = return_documents\n        return dict(params)\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 DashScope rerank\")\n        if \"documents\" not in optional_rerank_params:\n            raise ValueError(\"documents is required for DashScope rerank\")\n\n        request: Final[dict[str, Any]] = {\n            \"model\": model,\n            \"query\": optional_rerank_params[\"query\"],\n            \"documents\": optional_rerank_params[\"documents\"],\n        }\n        if optional_rerank_params.get(\"top_n\") is not None:\n            request[\"top_n\"] = optional_rerank_params[\"top_n\"]\n        if optional_rerank_params.get(\"return_documents\") is not None:\n            request[\"return_documents\"] = optional_rerank_params[\"return_documents\"]\n        return request\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":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/dashscope/rerank/transformation.py#L125-L161","documentation":"The DashScope rerank request transformer requires a 'documents' list; if the optional rerank params lack 'documents', a ValueError is raised before any network request. Rerank without candidate documents is meaningless, so the transformer refuses to build the request.","triggerScenarios":"Calling litellm.rerank(model=\"dashscope/...\", query=\"...\") without documents, or passing an empty/missing documents key through dynamic param construction.","commonSituations":"RAG retrieval step returned zero chunks and the pipeline still calls rerank; a variable named 'docs' vs 'documents' mismatch when assembling kwargs.","solutions":["Pass documents explicitly: litellm.rerank(model=..., query=q, documents=[\"text1\", \"text2\"])","Guard in the retrieval pipeline: skip rerank when the retrieved chunk list is empty","Verify the key name is exactly 'documents' (not 'docs', 'passages', 'texts')"],"exampleFix":"# before\nresp = litellm.rerank(model=\"dashscope/gte-rerank\", query=q)\n\n# after\nresp = litellm.rerank(model=\"dashscope/gte-rerank\", query=q, documents=[c[\"text\"] for c in retrieved])","handlingStrategy":"validation","validationCode":"if not isinstance(documents, list) or len(documents) == 0:\n    # nothing to rerank\n    return []  # or skip the call entirely","typeGuard":"def has_rerank_documents(params: dict) -> bool:\n    docs = params.get(\"documents\")\n    return isinstance(docs, list) and len(docs) > 0 and all(isinstance(d, str) for d in docs)","tryCatchPattern":"try:\n    resp = litellm.rerank(model=m, query=q, documents=docs)\nexcept ValueError as e:\n    if \"documents is required\" in str(e):\n        return []\n    raise","preventionTips":["Short-circuit the pipeline when retrieval returns zero chunks","Use keyword-only parameters (def rerank(*, query, documents)) in your wrapper so omission fails at call time"],"tags":["dashscope","rerank","validation","request"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}