{"record":{"id":"e8ef2c63eb02ab93","repo":"huggingface/transformers","slug":"audio-codebooks-need-at-least-one-channel-but-fou","errorCode":null,"errorMessage":"Audio codebooks need at least one channel, but found {num_channels} channels.","messagePattern":"Audio codebooks need at least one channel, but found (.+?) channels\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/logits_process.py","lineNumber":3095,"sourceCode":"    respective tokens to be (not) sampled.\n\n    <Tip warning={true}>\n\n    This logits processor is exclusively compatible with\n    [Dia](https://huggingface.co/docs/transformers/en/model_doc/dia).\n\n    </Tip>\n\n    Args:\n        num_channels (`int`):\n            Number of audio codebooks. Simplifies access to the first channel on the logits.\n        eos_token_id (`int`):\n            The id of *end-of-sequence* token.\n    \"\"\"\n\n    def __init__(self, num_channels: int, eos_token_id: int):\n        if num_channels < 1:\n            raise ValueError(f\"Audio codebooks need at least one channel, but found {num_channels} channels.\")\n        if eos_token_id < 1:\n            raise ValueError(f\"Expected `eos_token_id` to be a positive integer, found {eos_token_id} instead.\")\n\n        self.num_channels = num_channels\n        self.eos_id = eos_token_id\n\n    @add_start_docstrings(LOGITS_PROCESSOR_INPUTS_DOCSTRING)\n    def __call__(self, input_ids: torch.LongTensor, scores: torch.FloatTensor) -> torch.FloatTensor:\n        # Reshape for easier channel indexing [B, C, V]\n        scores = scores.reshape(-1, self.num_channels, scores.shape[-1])\n\n        # EOS filter\n        # 1. Condition: Only the first channel can generate the EOS token\n        # Side condition of disabling generation of special tokens (e.g. audio pad, bos, ...)\n        # (Assumes them to be greater than audio eos token position)\n        scores[:, 1:, self.eos_id :] = torch.full_like(\n            scores[:, 1:, self.eos_id :],\n            fill_value=-float(\"inf\"),","sourceCodeStart":3077,"sourceCodeEnd":3113,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/logits_process.py#L3077-L3113","documentation":"Thrown by the audio codebook logits processor's __init__ (used for multi-codebook audio generation, e.g. MusicGen-style models) when num_channels < 1. num_channels defines how many audio codebooks the processor slices out of the flat logits dimension; zero or negative channels make the reshape (-1, num_channels, vocab) impossible.","triggerScenarios":"Constructing the processor with num_channels=0 or negative; deriving num_channels from config.audio_channels / num codebooks of a checkpoint where the field is absent and defaults to 0.","commonSituations":"Loading a checkpoint whose config lacks the codebook-count attribute; arithmetic like num_channels = len(codebooks) - 1 on an empty list.","solutions":["Pass the actual number of audio codebooks from the model config (e.g. config.num_codebooks or decoder.num_codebooks), which must be >= 1.","If computing it dynamically, assert len(codebooks) > 0 before constructing.","Check for a config field typo reading the wrong attribute (getting 0 instead of 4)."],"exampleFix":"# before\nprocessor = AudioEosLogitsProcessor(num_channels=0, eos_token_id=eos_id)\n\n# after\nprocessor = AudioEosLogitsProcessor(num_channels=model.config.num_codebooks, eos_token_id=eos_id)","handlingStrategy":"validation","validationCode":"num_channels = getattr(model.config, \"num_codebooks\", None) or getattr(model.decoder.config, \"num_codebooks\", None)\nassert num_channels and num_channels >= 1, f\"invalid num_channels: {num_channels}\"","typeGuard":"def valid_num_channels(v) -> bool:\n    return isinstance(v, int) and v >= 1","tryCatchPattern":null,"preventionTips":["Always source num_channels from the checkpoint config, never hardcode arithmetic on possibly-empty lists.","Add a config smoke-test when loading new audio checkpoints."],"tags":["audio-generation","codebooks","config-validation","logits-processor"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}