BerriAI/litellm · error · ValueError

top_n must be a positive integer, got: {top_n!r}

Error message

top_n must be a positive integer, got: {top_n!r}

What it means

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.

Source

Thrown at litellm/llms/nvidia_nim/rerank/ranking_transformation.py:140

    def transform_rerank_request(
        self,
        model: str,
        optional_rerank_params: dict,
        headers: dict,
        litellm_params: dict | None = None,
    ) -> dict:
        """
        Transform request, using clean model name without 'ranking/' prefix.

        top_n / top_k are stripped from the outgoing request: the native
        /v1/ranking endpoint accepts only model, query, passages, and
        truncate. top_n is stashed and applied client-side in
        transform_rerank_response.
        """
        top_n: Final = optional_rerank_params.get("top_n")
        if top_n is not None:
            if isinstance(top_n, bool) or not isinstance(top_n, int) or top_n < 1:
                raise ValueError(f"top_n must be a positive integer, got: {top_n!r}")
            self._client_side_top_n = top_n

        clean_model: Final = self._get_clean_model_name(model)
        filtered_params: Final = {  # mutable-ok: the base transformer requires a mutable request dictionary
            k: v for k, v in optional_rerank_params.items() if k not in ("top_n", "top_k")
        }
        return super().transform_rerank_request(
            model=clean_model,
            optional_rerank_params=filtered_params,
            headers=headers,
            litellm_params=litellm_params,
        )

    def transform_rerank_response(
        self,
        model: str,
        raw_response: httpx.Response,
        model_response: RerankResponse,

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Pass a positive integer: top_n=3.
  2. Coerce before calling: top_n=int(value) after checking value >= 1.
  3. Omit top_n entirely if you want all results ranked.
  4. Validate user-supplied top_n at your API boundary before forwarding to rerank().

Example fix

# before
litellm.rerank(model="nvidia_nim/nv-rerankqa-mistral-4b-v3", query=q, documents=docs, top_n="5")

# after
top_n = int(raw_top_n) if str(raw_top_n).isdigit() and int(raw_top_n) >= 1 else None
kwargs = {"top_n": top_n} if top_n else {}
litellm.rerank(model="nvidia_nim/nv-rerankqa-mistral-4b-v3", query=q, documents=docs, **kwargs)
Defensive patterns

Strategy: validation

Validate before calling

def coerce_top_n(value):
    if value is None:
        return None
    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
        raise ValueError(f"top_n must be a positive integer, got {value!r}")
    return value

Type guard

def is_valid_top_n(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and value >= 1

Try / catch

try:
    litellm.rerank(model=m, query=q, documents=docs, top_n=top_n)
except ValueError as e:
    if "top_n must be a positive integer" in str(e):
        # bad user input: coerce or reject at the API boundary
        raise HTTPException(400, str(e)) from e
    raise

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/7b0c78e5baba6bf5. Report an issue: GitHub.