sgl-project/sglang · critical · ValueError

num_attention_heads must be positive.

Error message

num_attention_heads must be positive.

What it means

The MiniMax H3 DiT constructor validates that the architecture config's num_attention_heads is positive, because TP shards heads across ranks (num_attention_heads // tp_size) and attention projection weights are shaped by head count. A zero/negative value means a malformed or partially-loaded model config.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py:1807

    def _can_batch_block_adaln(self) -> bool:
        return (
            self.adaln_cache is None
            and get_tp_world_size() > 1
            and not torch.compiler.is_compiling()
            and not envs.SGLANG_CACHE_DIT_ENABLED
            and not hasattr(self, "_sglang_cache_dit_adapter")
            and not is_layerwise_offloaded_module(self)
            and all(type(block) is MiniMaxH3DiTBlock for block in self.blocks)
        )

    def _validate_tp_config(
        self, *, arch: MiniMaxH3DiTArchConfig, tp_size: int
    ) -> None:
        if tp_size <= 0:
            raise ValueError("TP size must be positive.")
        if arch.num_attention_heads <= 0:
            raise ValueError("num_attention_heads must be positive.")
        if arch.hidden_size <= 0:
            raise ValueError("hidden_size must be positive.")
        if arch.attention_head_dim <= 0:
            raise ValueError("attention_head_dim must be positive.")
        if arch.ffn_hidden_size <= 0:
            raise ValueError("ffn_hidden_size must be positive.")
        for name, value in (
            ("num_attention_heads", arch.num_attention_heads),
            ("hidden_size", arch.hidden_size),
            ("ffn_hidden_size", arch.ffn_hidden_size),
            ("time_embed_hidden_size", arch.time_embed_hidden_size),
            ("adaln_out_features", arch.adaln_out_features),
            ("final_adaln_out_features", arch.final_adaln_out_features),
            ("video_patch_output_dim", arch.latents_dim * math.prod(arch.patch_size)),
            ("audio_patch_output_dim", arch.audio_latents_dim),
        ):
            if value % tp_size:
                raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect the arch config object right before constructing the model and print num_attention_heads
2. Fix the source config: set num_attention_heads to the checkpoint's true head count (e.g. 24/48/64)
3. If loading from JSON, verify the key name matches MiniMaxH3DiTArchConfig's field names exactly

Example fix

# before
arch = MiniMaxH3DiTArchConfig(num_attention_heads=0, ...)
# after
arch = MiniMaxH3DiTArchConfig(num_attention_heads=48, ...)

assert arch.num_attention_heads > 0, f"bad num_attention_heads={arch.num_attention_heads}"

def heads_ok(arch) -> bool:
    return getattr(arch, "num_attention_heads", 0) > 0

When it happens

Trigger: Building the model from a hand-written MiniMaxH3DiTArchConfig or a JSON checkpoint config where num_attention_heads is 0, missing and defaulted to 0, or negative.

Common situations: Typos in a custom arch config; converting a checkpoint with a renamed field (n_heads vs num_attention_heads) so the field silently defaults to 0; editing a config template and dropping the field.

Related errors

• hidden_size must be positive.
• attention_head_dim must be positive.
• ffn_hidden_size must be positive.
• TP size must be positive.
• Invalid threshold_type for topk: {threshold_type}. Choose 'q

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