huggingface/transformers · error · ValueError

`min_tokens_to_keep` has to be a strictly positive integer,

Error message

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

What it means

Thrown by EpsilonLogitsWarper.__init__ when min_tokens_to_keep is < 1 after an int() coercion. Unlike sibling processors, this one coerces first (min_tokens_to_keep = int(...)), so a float like 2.5 silently becomes 2 — only values that truncate to 0 or less (0, 0.5, -1) raise. The message says 'strictly positive integer'.

Source

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

    <BLANKLINE>

    >>> # With epsilon sampling, the output gets restricted to high-probability tokens. Note that this is similar to
    >>> # Top P sampling, which restricts tokens based on their cumulative probability.
    >>> # Pro tip: The paper recommends using `epsilon_cutoff` values between 3e-4 and 9e-4
    >>> outputs = model.generate(**inputs, do_sample=True, epsilon_cutoff=0.1)
    >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
    A sequence: 1, 2, 3, 4, 5, 6, 7, 8, 9
    ```
    """

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

        min_tokens_to_keep = int(min_tokens_to_keep)
        if min_tokens_to_keep < 1:
            raise ValueError(
                f"`min_tokens_to_keep` has to be a strictly positive integer, but is {min_tokens_to_keep}"
            )

        self.epsilon = epsilon
        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:
        # Determine which indices to remove
        probabilities = scores.softmax(dim=-1)
        indices_to_remove = probabilities < self.epsilon

        # Keep the words with the 'min_tokens_to_keep'-highest probabilities
        top_k = min(self.min_tokens_to_keep, scores.size(-1))  # Safety check
        indices_to_remove = indices_to_remove & (scores < torch.topk(scores, top_k)[0][..., -1, None])

        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 (default)
2. Round deliberately before passing: max(1, round(x)) to avoid silent truncation surprises
3. Validate external input: reject anything < 1

Example fix

# before
proc = EpsilonLogitsWarper(9e-4, min_tokens_to_keep=0)  # ValueError

# after
proc = EpsilonLogitsWarper(9e-4, min_tokens_to_keep=1)

def valid_min_tokens(n):
    return float(n) >= 1  # note: constructor silently truncates via int()

def is_valid_min_tokens(n) -> bool:
    try:
        return int(n) >= 1
    except (TypeError, ValueError):
        return False

try:
    proc = EpsilonLogitsWarper(9e-4, min_tokens_to_keep=max(1, int(round(n))))
except ValueError as e:
    raise ValueError(f'min_tokens_to_keep={n!r} must be >= 1') from e

When it happens

Trigger: EpsilonLogitsWarper(3e-4, min_tokens_to_keep=0); min_tokens_to_keep=0.5; negative values.

Common situations: Config fields typed as floats where 0 means 'auto'; note also that fractional values are silently truncated rather than rejected, which can mask bugs.

Related errors

• `epsilon_cutoff` has to be a float > 0 and < 1, but is {epsi
• `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_p` has to be a float > 0 and < 1, but is {top_p}

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