{"record":{"id":"7b0c78e5baba6bf5","repo":"BerriAI/litellm","slug":"top-n-must-be-a-positive-integer-got-top-n-r","errorCode":null,"errorMessage":"top_n must be a positive integer, got: {top_n!r}","messagePattern":"top_n must be a positive integer, got: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/nvidia_nim/rerank/ranking_transformation.py","lineNumber":140,"sourceCode":"    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, using clean model name without 'ranking/' prefix.\n\n        top_n / top_k are stripped from the outgoing request: the native\n        /v1/ranking endpoint accepts only model, query, passages, and\n        truncate. top_n is stashed and applied client-side in\n        transform_rerank_response.\n        \"\"\"\n        top_n: Final = optional_rerank_params.get(\"top_n\")\n        if top_n is not None:\n            if isinstance(top_n, bool) or not isinstance(top_n, int) or top_n < 1:\n                raise ValueError(f\"top_n must be a positive integer, got: {top_n!r}\")\n            self._client_side_top_n = top_n\n\n        clean_model: Final = self._get_clean_model_name(model)\n        filtered_params: Final = {  # mutable-ok: the base transformer requires a mutable request dictionary\n            k: v for k, v in optional_rerank_params.items() if k not in (\"top_n\", \"top_k\")\n        }\n        return super().transform_rerank_request(\n            model=clean_model,\n            optional_rerank_params=filtered_params,\n            headers=headers,\n            litellm_params=litellm_params,\n        )\n\n    def transform_rerank_response(\n        self,\n        model: str,\n        raw_response: httpx.Response,\n        model_response: RerankResponse,","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/nvidia_nim/rerank/ranking_transformation.py#L122-L158","documentation":"Raised by litellm's Nvidia NIM ranking transformer when the optional top_n rerank parameter is present but invalid: it is a bool, not an int, or an int < 1. top_n is intentionally stripped from the outgoing request and applied client-side in the response transform, so it must be validated locally.","triggerScenarios":"Calling litellm.rerank(model='nvidia_nim/nv-rerankqa-mistral-4b-v3', ..., top_n=0), top_n=-1, top_n=2.0 (float), top_n=True, or top_n=\"3\" (string).","commonSituations":"Passing top_n from unvalidated user input or JSON config where numbers arrive as strings/floats, reusing Cohere-style defaults that don't apply, or computing top_n dynamically and allowing 0/negative values.","solutions":["Pass a positive integer: top_n=3.","Coerce before calling: top_n=int(value) after checking value >= 1.","Omit top_n entirely if you want all results ranked.","Validate user-supplied top_n at your API boundary before forwarding to rerank()."],"exampleFix":"# before\nlitellm.rerank(model=\"nvidia_nim/nv-rerankqa-mistral-4b-v3\", query=q, documents=docs, top_n=\"5\")\n\n# after\ntop_n = int(raw_top_n) if str(raw_top_n).isdigit() and int(raw_top_n) >= 1 else None\nkwargs = {\"top_n\": top_n} if top_n else {}\nlitellm.rerank(model=\"nvidia_nim/nv-rerankqa-mistral-4b-v3\", query=q, documents=docs, **kwargs)","handlingStrategy":"validation","validationCode":"def coerce_top_n(value):\n    if value is None:\n        return None\n    if isinstance(value, bool) or not isinstance(value, int) or value < 1:\n        raise ValueError(f\"top_n must be a positive integer, got {value!r}\")\n    return value","typeGuard":"def is_valid_top_n(value: object) -> bool:\n    return isinstance(value, int) and not isinstance(value, bool) and value >= 1","tryCatchPattern":"try:\n    litellm.rerank(model=m, query=q, documents=docs, top_n=top_n)\nexcept ValueError as e:\n    if \"top_n must be a positive integer\" in str(e):\n        # bad user input: coerce or reject at the API boundary\n        raise HTTPException(400, str(e)) from e\n    raise","preventionTips":["Validate numeric params at your API boundary, not deep in provider calls.","Coerce str/float inputs with int() only after a range check.","Remember bool is an int subclass in Python — exclude it explicitly."],"tags":["nvidia-nim","rerank","parameter-validation","top-n"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}