huggingface/transformers · error · ValueError

`epsilon_cutoff` has to be a float > 0 and < 1, but is {epsi

Error message

`epsilon_cutoff` has to be a float > 0 and < 1, but is {epsilon}

What it means

Thrown by EpsilonLogitsWarper.__init__ when epsilon is <= 0 or >= 1. Epsilon sampling removes tokens whose probability is below an absolute threshold epsilon, so it must be strictly inside (0, 1). The constructor coerces with float(epsilon), so ints and numeric strings are accepted if in range.

Source

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

    >>> outputs = model.generate(**inputs, do_sample=True)
    >>> print(tokenizer.batch_decode(outputs, skip_special_tokens=True)[0])
    A sequence: 1, 2, 3 | < 4 (left-hand pointer) ;
    <BLANKLINE>
    <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

View on GitHub (pinned to a597f97485)

Solutions

1. To disable epsilon sampling, remove epsilon_cutoff from the generate call / config
2. Otherwise pass a small float in (0, 1): epsilon_cutoff=3e-4 (recommended 3e-4 to 9e-4)
3. Validate 0 < epsilon_cutoff < 1 in config-loading code

Example fix

# before
out = model.generate(**inputs, do_sample=True, epsilon_cutoff=0)  # 'disable' -> ValueError

# after
out = model.generate(**inputs, do_sample=True)  # disabled by omission
# or a valid value:
out = model.generate(**inputs, do_sample=True, epsilon_cutoff=9e-4)

def valid_epsilon(e):
    return isinstance(e, (int, float)) and 0.0 < float(e) < 1.0

def is_valid_epsilon(e) -> bool:
    return isinstance(e, (int, float)) and 0.0 < e < 1.0

try:
    proc = EpsilonLogitsWarper(float(e))
except ValueError as e:
    raise ValueError(f'epsilon_cutoff={e!r} must be in (0, 1); omit it to disable') from e

When it happens

Trigger: EpsilonLogitsWarper(0.0); epsilon=1.0; epsilon=-1e-4; model.generate(do_sample=True, epsilon_cutoff=0) where 0 was intended to disable it.

Common situations: Using 0 as an 'off' sentinel in configs (here it raises — omit the parameter instead); values outside the paper's recommended 3e-4–9e-4 range by mistake; percentage confusion.

Related errors

• `min_tokens_to_keep` has to be a strictly positive integer,
• `eta_cutoff` has to be a float > 0 and < 1, but is {epsilon}
• `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

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