{"record":{"id":"373a01e8b8c20c63","repo":"BerriAI/litellm","slug":"documents-is-required-for-vertex-ai-rerank","errorCode":null,"errorMessage":"documents is required for Vertex AI rerank","messagePattern":"documents is required for Vertex AI rerank","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/vertex_ai/rerank/transformation.py","lineNumber":119,"sourceCode":"            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        \"\"\"\n        Transform the request from Cohere format to Vertex AI Discovery Engine format\n        \"\"\"\n        if \"query\" not in optional_rerank_params:\n            raise ValueError(\"query is required for Vertex AI rerank\")\n        if \"documents\" not in optional_rerank_params:\n            raise ValueError(\"documents is required for Vertex AI rerank\")\n\n        query: Final = optional_rerank_params[\"query\"]\n        documents: Final = optional_rerank_params[\"documents\"]\n        top_n: Final = optional_rerank_params.get(\"top_n\", None)\n        return_documents: Final = optional_rerank_params.get(\"return_documents\", True)\n\n        # Convert documents to records format\n        records: Final = []\n        for idx, document in enumerate(documents):\n            if isinstance(document, str):\n                content = document\n                title = \" \".join(document.split()[:3])  # First 3 words as title\n            else:\n                # Handle dict format\n                content = document.get(\"text\", str(document))\n                title = document.get(\"title\", \" \".join(content.split()[:3]))\n\n            records.append({\"id\": str(idx), \"title\": title, \"content\": content})","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/llms/vertex_ai/rerank/transformation.py#L101-L137","documentation":"ValueError raised in transform_rerank_request when 'documents' is missing from the rerank parameters. Documents (a list of strings or of dicts with id/content) are the payload being ranked; without them there is nothing to send to the Discovery Engine rank endpoint.","triggerScenarios":"Calling litellm.rerank with only a query; the documents key misspelled ('docs', 'texts'); documents passed as a positional argument the handler does not read.","commonSituations":"Dynamic param construction dropping empty lists; schema drift from other rerank providers; thin wrappers that forward the wrong field names.","solutions":["Pass documents=[...] - a list of strings or of dicts","Verify the exact key name is 'documents'","Guard with a pre-call check (see defense)"],"exampleFix":"# before\nlitellm.rerank(model='vertex_ai/semantic-ranker', query='q')\n\n# after\nlitellm.rerank(\n    model='vertex_ai/semantic-ranker',\n    query='q',\n    documents=['doc one text', 'doc two text'],\n)","handlingStrategy":"validation","validationCode":"def valid_rerank_documents(params: dict) -> bool:\n    docs = params.get('documents')\n    return isinstance(docs, list) and len(docs) > 0","typeGuard":"def is_rerank_request(value: dict) -> bool:\n    docs = value.get('documents') if isinstance(value, dict) else None\n    return (\n        isinstance(docs, list)\n        and len(docs) > 0\n        and all(isinstance(d, (str, dict)) for d in docs)\n    )","tryCatchPattern":"try:\n    resp = litellm.rerank(model=model, **params)\nexcept ValueError as e:\n    if 'documents is required' in str(e):\n        raise SystemExit('Missing rerank documents')\n    raise","preventionTips":["Require a non-empty documents list in your API schema","Standardize the key name 'documents' across your codebase","Add a unit test asserting rerank params always include query and documents"],"tags":["vertex-ai","rerank","request-validation","missing-parameter"],"backgroundTag":"missing-required-parameter","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T10:36:37.832Z"}