{"record":{"id":"5211f83e2746b09a","repo":"BerriAI/litellm","slug":"documents-is-required-for-fireworks-ai-rerank","errorCode":null,"errorMessage":"documents is required for Fireworks AI rerank","messagePattern":"documents is required for Fireworks AI rerank","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/fireworks_ai/rerank/transformation.py","lineNumber":137,"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 request to Fireworks AI rerank format\n        \"\"\"\n        if \"query\" not in optional_rerank_params:\n            raise ValueError(\"query is required for Fireworks AI rerank\")\n        if \"documents\" not in optional_rerank_params:\n            raise ValueError(\"documents is required for Fireworks AI rerank\")\n\n        # Handle model name - Fireworks AI expects model name like \"fireworks/qwen3-reranker-8b\"\n        # Remove fireworks_ai/ prefix if present\n        if model.startswith(\"fireworks_ai/\"):\n            model = model.replace(\"fireworks_ai/\", \"\")\n\n        # If model doesn't start with \"fireworks/\", add it\n        # But don't add if it already has the prefix\n        if not model.startswith(\"fireworks/\"):\n            model = f\"fireworks/{model}\"\n\n        request_data: Final = {\n            \"model\": model,\n            \"query\": optional_rerank_params[\"query\"],\n            \"documents\": optional_rerank_params[\"documents\"],\n        }\n\n        if \"top_n\" in optional_rerank_params and optional_rerank_params[\"top_n\"] is not None:","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/fireworks_ai/rerank/transformation.py#L119-L155","documentation":"The second half of the rerank request contract check: transform_rerank_request() requires a 'documents' list alongside 'query'. Without documents there is nothing to rank, so the transformation raises this ValueError before any HTTP request is sent.","triggerScenarios":"Calling litellm.rerank(model='fireworks_ai/...', query='...') with documents omitted, set to an empty dict, or under a misspelled key like 'docs' or 'texts'.","commonSituations":"Upstream retrieval step returned no items and the caller forwarded kwargs anyway; parameter renamed when migrating from Cohere's rerank API; dynamically constructed optional params where the documents branch never executes.","solutions":["Include documents as a list of strings: litellm.rerank(model=..., query=..., documents=['a', 'b']).","Guard upstream: skip or short-circuit the rerank call when the retrieved document list is empty.","Verify the exact key name 'documents' in dynamically built kwargs (not 'docs', 'texts', 'inputs')."],"exampleFix":"# before\nresults = litellm.rerank(model=\"fireworks_ai/fireworks/qwen3-reranker-8b\", query=\"find doc1\")\n\n# after\nresults = litellm.rerank(model=\"fireworks_ai/fireworks/qwen3-reranker-8b\", query=\"find doc1\", documents=[\"doc1\", \"doc2\"])","handlingStrategy":"validation","validationCode":"def rerank_or_none(model: str, query: str, documents: list[str] | None):\n    if not documents:  # nothing to rank; skip the API call entirely\n        return None\n    return litellm.rerank(model=model, query=query, documents=documents)","typeGuard":"def has_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    litellm.rerank(**params)\nexcept ValueError as e:\n    if \"documents is required\" in str(e):\n        return []  # retrieval returned nothing upstream\n    raise","preventionTips":["Guard the retrieval-to-rerank pipeline: empty retrieval results should skip rerank, not call it.","Keep parameter names exactly 'query' and 'documents' — add a lint/assert on the kwargs dict.","Port tests when migrating from other rerank SDKs; their parameter names differ."],"tags":["fireworks-ai","rerank","validation","request-validation"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}