huggingface/transformers · error · ValueError

`min_tokens_to_keep` has to be a positive integer, but is {m

Error message

`min_tokens_to_keep` has to be a positive integer, but is {min_tokens_to_keep}

What it means

Thrown by TopPLogitsWarper.__init__ when min_tokens_to_keep is not a Python int or is < 1. This parameter guarantees at least that many tokens survive nucleus filtering, which requires a positive integer count. bool values pass isinstance (bool subclasses int) but True==1 is a legal value anyway.

Source

Thrown at src/transformers/generation/logits_process.py:520

    <BLANKLINE>
    <BLANKLINE>

    >>> # With `top_p` sampling, the output gets restricted to high-probability tokens.
    >>> # Pro tip: In practice, LLMs use `top_p` in the 0.9-0.95 range.
    >>> outputs = model.generate(**inputs, do_sample=True, top_p=0.1)
    >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
    A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9
    ```
    """

    supports_continuous_batching = True

    def __init__(self, top_p: float, filter_value: float = -float("Inf"), min_tokens_to_keep: int = 1):
        top_p = float(top_p)
        if top_p < 0 or top_p > 1.0:
            raise ValueError(f"`top_p` has to be a float > 0 and < 1, but is {top_p}")
        if not isinstance(min_tokens_to_keep, int) or (min_tokens_to_keep < 1):
            raise ValueError(f"`min_tokens_to_keep` has to be a positive integer, but is {min_tokens_to_keep}")

        self.top_p = top_p
        self.filter_value = filter_value
        self.min_tokens_to_keep = min_tokens_to_keep

    @add_start_docstrings(LOGITS_PROCESSOR_INPUTS_DOCSTRING)
    def __call__(self, input_ids: torch.LongTensor, scores: torch.FloatTensor) -> torch.FloatTensor:
        sorted_logits, sorted_indices = torch.sort(scores, descending=False)
        cumulative_probs = sorted_logits.softmax(dim=-1).cumsum(dim=-1)

        # Remove tokens with cumulative top_p above the threshold (token with 0 are kept)
        sorted_indices_to_remove = cumulative_probs <= (1 - self.top_p)
        # Keep at least min_tokens_to_keep
        sorted_indices_to_remove[..., -self.min_tokens_to_keep :] = 0

        # scatter sorted tensors to original indexing
        indices_to_remove = sorted_indices_to_remove.scatter(1, sorted_indices, sorted_indices_to_remove)
        scores_processed = scores.masked_fill(indices_to_remove, self.filter_value)

View on GitHub (pinned to a597f97485)

Solutions

1. Pass a positive int: min_tokens_to_keep=1 (the default) or higher
2. Coerce and floor computed values: max(1, int(round(ratio * vocab_size)))
3. Sanitize external input before building the warper

Example fix

# before
proc = TopPLogitsWarper(0.9, min_tokens_to_keep=0)  # ValueError

# after
proc = TopPLogitsWarper(0.9, min_tokens_to_keep=1)

def valid_min_tokens(n):
    return isinstance(n, int) and n >= 1

def is_valid_min_tokens(n) -> bool:
    return type(n) is int and n >= 1

try:
    proc = TopPLogitsWarper(0.9, min_tokens_to_keep=int(max(1, n)))
except ValueError as e:
    raise ValueError(f'min_tokens_to_keep={n!r} must be >= 1') from e

When it happens

Trigger: TopPLogitsWarper(0.9, min_tokens_to_keep=0); passing a float like 2.0; passing a numpy integer.

Common situations: Exposing min_tokens_to_keep in a user-facing API without validation; config values deserialized as strings or floats; deriving the value from a ratio instead of a count.

Related errors

• `top_p` has to be a float > 0 and < 1, but is {top_p}
• `temperature` (={temperature}) has to be a strictly positive
• `penalty` has to be a strictly positive float, but is {penal
• `prompt_ignore_length` has to be a positive integer, but is
• `top_k` has to be a strictly positive integer, but is {top_k

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/57fc011e44c8c700. Report an issue: GitHub.