{"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":null,"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/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/llms/dashscope/rerank/transformation.py#L125-L161","documentation":"The sibling check to the query guard: transform_rerank_request also hard-requires 'documents' and raises ValueError('documents is required for DashScope rerank') when the params dict lacks it. Pure client-side validation — nothing was sent to DashScope.","triggerScenarios":"litellm.rerank(model='dashscope/...', query='...') with documents omitted or None; retrieval step returned zero candidates and the caller forwarded an empty/absent documents value; kwargs-forwarding wrapper that swallows the documents field.","commonSituations":"RAG flow where the retriever found no chunks and code proceeds to rerank anyway; documents built conditionally and skipped on an empty branch; renaming from 'docs' or 'passages' during migration.","solutions":["Pass a non-empty documents list: litellm.rerank(model=..., query=..., documents=[...])","Guard upstream: skip the rerank call entirely when retrieval returns zero documents instead of letting it fail","Check for key-name mismatches ('docs', 'passages') in forwarded kwargs"],"exampleFix":"# before\ndocs = retriever.search(q)  # returns []\nlitellm.rerank(model='dashscope/gte-rerank', query=q, documents=docs)  # ValueError (or would send nothing)\n\n# after\ndocs = retriever.search(q)\nif docs:\n    litellm.rerank(model='dashscope/gte-rerank', query=q, documents=docs)\nelse:\n    results = []  # short-circuit: nothing to rerank","handlingStrategy":"validation","validationCode":"def should_rerank(query: str, docs: list) -> bool:\n    return bool(isinstance(query, str) and query.strip() and isinstance(docs, list) and len(docs) > 0)\n\nif should_rerank(query, retrieved):\n    result = litellm.rerank(model='dashscope/gte-rerank', query=query, documents=retrieved)","typeGuard":"def has_valid_documents(params: dict) -> bool:\n    d = params.get('documents')\n    return isinstance(d, list) and len(d) > 0 and all(isinstance(x, str) for x in d)","tryCatchPattern":"try:\n    litellm.rerank(model='dashscope/gte-rerank', **params)\nexcept ValueError as e:\n    if 'documents is required' in str(e):\n        return []  # nothing retrieved upstream - nothing to rerank\n    raise","preventionTips":["Skip rerank when retrieval yields zero documents rather than letting the call fail","Enforce non-empty lists in your internal request schema, not at the provider boundary"],"tags":["dashscope","rerank","required-parameter","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}