huggingface/transformers · error · ValueError

`sequence_bias` has to be a non-empty dictionary, or non-emp

Error message

`sequence_bias` has to be a non-empty dictionary, or non-empty list of lists but is {sequence_bias}.

What it means

Thrown by SequenceBiasLogitsProcessor._validate_arguments when sequence_bias is not a dict or list, or is empty. The processor needs at least one (token-sequence -> bias) entry to do anything; subsequent checks additionally require dict keys to be tuples of non-negative ints. An empty structure almost always signals a bug in the code that built the bias.

Source

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

        # Precompute the bias tensors to be applied. Sequences of length 1 are kept separately, as they can be applied
        # with simpler logic.
        self.length_1_bias = torch.zeros((vocabulary_size,), dtype=torch.float, device=scores.device)
        # Extract single-token sequences and their biases
        single_token_ids = []
        single_token_biases = []
        for sequence_ids, bias in self.sequence_bias.items():
            if len(sequence_ids) == 1:
                single_token_ids.append(sequence_ids[0])
                single_token_biases.append(bias)

        if single_token_ids:  # Only if we have any single-token sequences
            self.length_1_bias[single_token_ids] = torch.tensor(single_token_biases, device=scores.device)
        self.prepared_bias_variables = True

    def _validate_arguments(self):
        sequence_bias = self.sequence_bias
        if not isinstance(sequence_bias, dict) and not isinstance(sequence_bias, list) or len(sequence_bias) == 0:
            raise ValueError(
                f"`sequence_bias` has to be a non-empty dictionary, or non-empty list of lists but is {sequence_bias}."
            )
        if isinstance(sequence_bias, dict) and any(
            not isinstance(sequence_ids, tuple) for sequence_ids in sequence_bias
        ):
            raise ValueError(f"`sequence_bias` has to be a dict with tuples as keys, but is {sequence_bias}.")
        if isinstance(sequence_bias, dict) and any(
            any((not isinstance(token_id, (int, np.integer)) or token_id < 0) for token_id in sequence_ids)
            or len(sequence_ids) == 0
            for sequence_ids in sequence_bias
        ):
            raise ValueError(
                f"Each key in `sequence_bias` has to be a non-empty tuple of positive integers, but is "
                f"{sequence_bias}."
            )

        def all_token_bias_pairs_are_valid(sequence):
            return (

View on GitHub (pinned to a597f97485)

Solutions

Skip biasing when the dict/list is empty instead of constructing the processor (empty bias is a no-op anyway)
If using a dict, use tuples of int ids as keys: {(token_id,): 2.0} or {(id1, id2): -1.0}
Log or assert when your bias-building step produces zero entries — it usually means tokenization or filtering failed upstream

Example fix

# before
proc = SequenceBiasLogitsProcessor(sequence_bias={})  # ValueError

# after
biases = {(tokenizer.convert_tokens_to_ids('Paris'),): 5.0}
procs = [SequenceBiasLogitsProcessor(sequence_bias=biases)] if biases else []
out = model.generate(**inputs, logits_processor=procs)

Defensive patterns

Strategy: validation

Validate before calling

def usable_sequence_bias(sb):
    return isinstance(sb, (dict, list)) and len(sb) > 0

# skip biasing when empty:
procs = [SequenceBiasLogitsProcessor(sequence_bias=sb)] if usable_sequence_bias(sb) else []

Type guard

def is_usable_sequence_bias(sb) -> bool:
    return isinstance(sb, (dict, list)) and len(sb) > 0

Try / catch

try:
    proc = SequenceBiasLogitsProcessor(sequence_bias=sb)
except ValueError as e:
    raise ValueError(f'sequence_bias unusable ({sb!r}); did tokenization/filtering return nothing?') from e

Prevention

Guard the builder: if your tokenization/filter step yields no entries, skip the processor
Dict keys must be tuples of non-negative ints, e.g. {(id,): 2.0}
Log a warning when bias construction produces an empty structure — it usually masks an upstream bug

When it happens

Trigger: SequenceBiasLogitsProcessor(sequence_bias={}); passing a list that came back empty after filtering (e.g. no tokens matched); passing None or a pandas Series instead of a dict/list; model.generate(sequence_bias={}) via config plumbing.

Common situations: Programmatically building biases from tokenized phrases where tokenization yields nothing (empty prompt, wrong tokenizer); filtering out-of-vocab ids and passing the emptied result; default-arg patterns that produce {} when a look-up fails.

Related errors

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