{"record":{"id":"042a73cbab50e839","repo":"huggingface/transformers","slug":"sequence-bias-has-to-be-a-non-empty-dictionary","errorCode":null,"errorMessage":"`sequence_bias` has to be a non-empty dictionary, or non-empty list of lists but is {sequence_bias}.","messagePattern":"`sequence_bias` has to be a non-empty dictionary, or non-empty list of lists but is (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/logits_process.py","lineNumber":1354,"sourceCode":"        # Precompute the bias tensors to be applied. Sequences of length 1 are kept separately, as they can be applied\n        # with simpler logic.\n        self.length_1_bias = torch.zeros((vocabulary_size,), dtype=torch.float, device=scores.device)\n        # Extract single-token sequences and their biases\n        single_token_ids = []\n        single_token_biases = []\n        for sequence_ids, bias in self.sequence_bias.items():\n            if len(sequence_ids) == 1:\n                single_token_ids.append(sequence_ids[0])\n                single_token_biases.append(bias)\n\n        if single_token_ids:  # Only if we have any single-token sequences\n            self.length_1_bias[single_token_ids] = torch.tensor(single_token_biases, device=scores.device)\n        self.prepared_bias_variables = True\n\n    def _validate_arguments(self):\n        sequence_bias = self.sequence_bias\n        if not isinstance(sequence_bias, dict) and not isinstance(sequence_bias, list) or len(sequence_bias) == 0:\n            raise ValueError(\n                f\"`sequence_bias` has to be a non-empty dictionary, or non-empty list of lists but is {sequence_bias}.\"\n            )\n        if isinstance(sequence_bias, dict) and any(\n            not isinstance(sequence_ids, tuple) for sequence_ids in sequence_bias\n        ):\n            raise ValueError(f\"`sequence_bias` has to be a dict with tuples as keys, but is {sequence_bias}.\")\n        if isinstance(sequence_bias, dict) and any(\n            any((not isinstance(token_id, (int, np.integer)) or token_id < 0) for token_id in sequence_ids)\n            or len(sequence_ids) == 0\n            for sequence_ids in sequence_bias\n        ):\n            raise ValueError(\n                f\"Each key in `sequence_bias` has to be a non-empty tuple of positive integers, but is \"\n                f\"{sequence_bias}.\"\n            )\n\n        def all_token_bias_pairs_are_valid(sequence):\n            return (","sourceCodeStart":1336,"sourceCodeEnd":1372,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/logits_process.py#L1336-L1372","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nproc = SequenceBiasLogitsProcessor(sequence_bias={})  # ValueError\n\n# after\nbiases = {(tokenizer.convert_tokens_to_ids('Paris'),): 5.0}\nprocs = [SequenceBiasLogitsProcessor(sequence_bias=biases)] if biases else []\nout = model.generate(**inputs, logits_processor=procs)","handlingStrategy":"validation","validationCode":"def usable_sequence_bias(sb):\n    return isinstance(sb, (dict, list)) and len(sb) > 0\n\n# skip biasing when empty:\nprocs = [SequenceBiasLogitsProcessor(sequence_bias=sb)] if usable_sequence_bias(sb) else []","typeGuard":"def is_usable_sequence_bias(sb) -> bool:\n    return isinstance(sb, (dict, list)) and len(sb) > 0","tryCatchPattern":"try:\n    proc = SequenceBiasLogitsProcessor(sequence_bias=sb)\nexcept ValueError as e:\n    raise ValueError(f'sequence_bias unusable ({sb!r}); did tokenization/filtering return nothing?') from e","preventionTips":["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"],"tags":["generation","sequence-bias","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}