sgl-project/sglang · error · ValueError

audio_out_channels must be divisible by tp_size for TP-shard

Error message

audio_out_channels must be divisible by tp_size for TP-sharded output projection, got {arch.audio_out_channels=} {tp_size=}.

What it means

LTX-2's audio output projection is also TP-sharded, so arch.audio_out_channels must be divisible by tp_size at model construction. The check mirrors the video out_channels check and fails fast with both values in the message.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/ltx_2.py:1637

                f"{self.audio_num_attention_heads=} {tp_size=}."
            )
        if self.hidden_size % tp_size != 0:
            raise ValueError(
                "hidden_size must be divisible by tp_size for TP-sharded projections, got "
                f"{self.hidden_size=} {tp_size=}."
            )
        if self.audio_hidden_size % tp_size != 0:
            raise ValueError(
                "audio_hidden_size must be divisible by tp_size for TP-sharded projections, got "
                f"{self.audio_hidden_size=} {tp_size=}."
            )
        if int(arch.out_channels) % tp_size != 0:
            raise ValueError(
                "out_channels must be divisible by tp_size for TP-sharded output projection, got "
                f"{arch.out_channels=} {tp_size=}."
            )
        if int(arch.audio_out_channels) % tp_size != 0:
            raise ValueError(
                "audio_out_channels must be divisible by tp_size for TP-sharded output projection, got "
                f"{arch.audio_out_channels=} {tp_size=}."
            )

    def __init__(
        self,
        config: LTX2Config,
        hf_config: dict[str, Any],
        quant_config: QuantizationConfig | None = None,
    ) -> None:
        super().__init__(config=config, hf_config=hf_config)

        arch = self.config
        # Checkpoint naming is arch-config metadata, not a runtime capability.
        self.param_names_mapping = arch.param_names_mapping
        self.reverse_param_names_mapping = arch.reverse_param_names_mapping
        self.lora_param_names_mapping = arch.lora_param_names_mapping
        self.hidden_size = arch.hidden_size

View on GitHub (pinned to 0132848349)

Solutions

1. Choose tp_size that divides both out_channels and audio_out_channels (compute gcd of the two and use a divisor of it)
2. Check the checkpoint config's audio_out_channels value and factorize it before selecting TP degree
3. Fall back to tp_size=1 or a lower TP degree if no common divisor >= desired parallelism exists

Example fix

# before
import math
tp_size = 8  # audio_out_channels=12 -> fails

# after
tp_size = math.gcd(arch.out_channels, int(arch.audio_out_channels))
# or explicitly: tp_size = 2

import math
common = math.gcd(int(arch.out_channels), int(arch.audio_out_channels))
assert tp_size <= common and common % tp_size == 0, 'tp must divide both channel counts'

When it happens

Trigger: Building the LTX-2 model with a tp_size that divides out_channels but not audio_out_channels (e.g. video channels divisible by 8 but audio channels divisible only by 2), common with mixed audio/video architectures.

Common situations: Audio-enabled LTX-2 checkpoints where audio_out_channels is smaller or differently factored than video out_channels; scaling TP to many GPUs; misreading the config and passing a clap/audio dim instead of audio_out_channels.

Related errors

• out_channels must be divisible by tp_size for TP-sharded out
• Invalid {self.vae_scale_factor=}. Must be > 0.
• Invalid {self.patch_size=}. Must be > 0.
• Invalid spatial patching for packed token latents. Expected
• dim {dim} must be divisible by head_dim {head_dim}.

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/7db9ce0abbde999d. Report an issue: GitHub.