huggingface/transformers · error · ValueError

Audio codebooks need at least one channel, but found {num_ch

Error message

Audio codebooks need at least one channel, but found {num_channels} channels.

What it means

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.

Source

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

    respective tokens to be (not) sampled.

    <Tip warning={true}>

    This logits processor is exclusively compatible with
    [Dia](https://huggingface.co/docs/transformers/en/model_doc/dia).

    </Tip>

    Args:
        num_channels (`int`):
            Number of audio codebooks. Simplifies access to the first channel on the logits.
        eos_token_id (`int`):
            The id of *end-of-sequence* token.
    """

    def __init__(self, num_channels: int, eos_token_id: int):
        if num_channels < 1:
            raise ValueError(f"Audio codebooks need at least one channel, but found {num_channels} channels.")
        if eos_token_id < 1:
            raise ValueError(f"Expected `eos_token_id` to be a positive integer, found {eos_token_id} instead.")

        self.num_channels = num_channels
        self.eos_id = eos_token_id

    @add_start_docstrings(LOGITS_PROCESSOR_INPUTS_DOCSTRING)
    def __call__(self, input_ids: torch.LongTensor, scores: torch.FloatTensor) -> torch.FloatTensor:
        # Reshape for easier channel indexing [B, C, V]
        scores = scores.reshape(-1, self.num_channels, scores.shape[-1])

        # EOS filter
        # 1. Condition: Only the first channel can generate the EOS token
        # Side condition of disabling generation of special tokens (e.g. audio pad, bos, ...)
        # (Assumes them to be greater than audio eos token position)
        scores[:, 1:, self.eos_id :] = torch.full_like(
            scores[:, 1:, self.eos_id :],
            fill_value=-float("inf"),

View on GitHub (pinned to a597f97485)

Solutions

1. Pass the actual number of audio codebooks from the model config (e.g. config.num_codebooks or decoder.num_codebooks), which must be >= 1.
2. If computing it dynamically, assert len(codebooks) > 0 before constructing.
3. Check for a config field typo reading the wrong attribute (getting 0 instead of 4).

Example fix

# before
processor = AudioEosLogitsProcessor(num_channels=0, eos_token_id=eos_id)

# after
processor = AudioEosLogitsProcessor(num_channels=model.config.num_codebooks, eos_token_id=eos_id)

num_channels = getattr(model.config, "num_codebooks", None) or getattr(model.decoder.config, "num_codebooks", None)
assert num_channels and num_channels >= 1, f"invalid num_channels: {num_channels}"

def valid_num_channels(v) -> bool:
    return isinstance(v, int) and v >= 1

When it happens

Trigger: 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.

Common situations: Loading a checkpoint whose config lacks the codebook-count attribute; arithmetic like num_channels = len(codebooks) - 1 on an empty list.

Related errors

• Expected `eos_token_id` to be a positive integer, found {eos
• Unknown fusion type: {fusion_name}
• Invalid fusion config for {fusion_name}: expected `True`, `F
• logit_processor_kwargs['{key}'] has type {type(value).__name
• Unknown logit_processor_kwargs: {unknown_keys}. {self.suppor

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