{"record":{"id":"a8fe84e723cdc077","repo":"BerriAI/litellm","slug":"documents-is-required-for-nvidia-nim-rerank","errorCode":null,"errorMessage":"documents is required for Nvidia NIM rerank","messagePattern":"documents is required for Nvidia NIM rerank","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/nvidia_nim/rerank/transformation.py","lineNumber":200,"sourceCode":"        headers: dict,\n        litellm_params: dict | None = None,\n    ) -> dict:\n        \"\"\"\n        Transform request to Nvidia NIM format.\n\n        Nvidia NIM expects:\n        - query as {text: \"...\"}\n        - documents as passages: [{text: \"...\"}, ...]\n        - Optional: truncate (NONE or END), top_k\n\n        Note: optional_rerank_params may contain provider-specific params like 'top_k' and 'truncate'\n        that aren't in the OptionalRerankParams TypedDict but are passed through at runtime.\n        The mapping from Cohere's 'top_n' to Nvidia's 'top_k' already happened in map_cohere_rerank_params.\n        \"\"\"\n        if \"query\" not in optional_rerank_params:\n            raise ValueError(\"query is required for Nvidia NIM rerank\")\n        if \"documents\" not in optional_rerank_params:\n            raise ValueError(\"documents is required for Nvidia NIM rerank\")\n\n        query: Final = optional_rerank_params[\"query\"]\n        documents: Final = optional_rerank_params[\"documents\"]\n\n        # Transform query to object format\n        query_obj: Final[NvidiaNimQueryObject] = {\"text\": query}\n\n        # Transform documents to passages format\n        passages: Final[list[NvidiaNimPassageObject]] = []\n        for doc in documents:\n            if isinstance(doc, str):\n                passages.append({\"text\": doc})\n            elif isinstance(doc, dict):\n                # Preserve only the structured passage fields supported by the\n                # selected rerank route.\n                supported_fields: NvidiaNimPassageObject = {}  # mutable-ok: assembling a request TypedDict\n                if \"text\" in self.SUPPORTED_PASSAGE_FIELDS and \"text\" in doc:\n                    supported_fields[\"text\"] = doc[\"text\"]","sourceCodeStart":182,"sourceCodeEnd":218,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/nvidia_nim/rerank/transformation.py#L182-L218","documentation":"Raised by litellm's Nvidia NIM rerank transformer in transform_rerank_request when 'documents' is absent from optional_rerank_params. The native NIM ranking endpoint requires passages to rank; without documents there is nothing to send, so litellm aborts request construction.","triggerScenarios":"Calling litellm.rerank(model='nvidia_nim/...') with a query but no documents argument, or an empty/misspelled documents key (e.g. docs=[...]) so the parameter never reaches the transformer.","commonSituations":"Dynamic pipelines where the retrieval step returned nothing and documents was omitted instead of short-circuited, or parameter naming mismatched when porting from Cohere-style calls.","solutions":["Pass documents=[...] alongside query.","Short-circuit upstream: if not documents, skip the rerank call entirely.","Check the exact spelling 'documents' in your kwargs."],"exampleFix":"# before\nresults = litellm.rerank(model=m, query=q)  # forgot documents\n\n# after\nif not docs:\n    return []\nresults = litellm.rerank(model=m, query=q, documents=docs)","handlingStrategy":"validation","validationCode":"if not docs:\n    return []  # nothing to rank — skip the provider call entirely","typeGuard":"def has_rankable_documents(value: object) -> bool:\n    return isinstance(value, (list, tuple)) and len(value) > 0","tryCatchPattern":"try:\n    litellm.rerank(model=m, query=q, documents=docs)\nexcept ValueError as e:\n    if \"documents is required\" in str(e):\n        return []  # graceful no-op when retrieval found nothing\n    raise","preventionTips":["Short-circuit on empty retrieval results before calling rerank.","Validate documents is a non-empty list at request intake.","Check the exact kwarg spelling 'documents' when porting code from Cohere-style APIs."],"tags":["nvidia-nim","rerank","missing-parameter","documents"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}