sgl-project/sglang · critical · ValueError

TP size must be positive.

Error message

TP size must be positive.

What it means

Raised by MiniMaxH3DiT's _validate_tp_config during __init__ when the tensor-parallel size is zero or negative. The DiT shards attention/FFN weights across TP ranks, so a non-positive TP size makes all the per-rank shape math invalid, and the constructor fails fast before any weights are allocated.

Source

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

        self.adaln_cache.build(step_timesteps, embed=embed)

    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),
        ):

View on GitHub (pinned to 0132848349)

Solutions

1. Set tp_size to a positive power-of-two divisor of num_attention_heads, e.g. 1, 2, 4, 8
2. Check where tp_size originates: unset env vars, int(None), or world_size read before init_process_group
3. Add an assertion/default in your launch script: tp_size = tp_size or 1

Example fix

// before
model = MiniMaxH3DiT(config=cfg, tp_size=0)
// after
model = MiniMaxH3DiT(config=cfg, tp_size=max(1, args.tp_size))

tp_size = args.tp if args.tp and args.tp > 0 else 1
assert tp_size > 0 and arch.num_attention_heads % tp_size == 0

def valid_tp(tp: int) -> bool:
    return isinstance(tp, int) and tp > 0

When it happens

Trigger: Constructing the MiniMax H3 DiT model with tp_size=0 or a negative value, e.g. passing --tp-size 0 or a default/int parsing bug that yields 0 (unset env var coerced to int).

Common situations: Launching with a missing/miscomputed tp argument; scripts that derive tp_size from world_size when the distributed group hasn't been initialized yet (world_size=0); config typos like tp=-1.

Related errors

• num_attention_heads must be positive.
• hidden_size must be positive.
• attention_head_dim must be positive.
• ffn_hidden_size must be positive.
• MiniMax H3 {name}={value} must be divisible by TP size {tp_s

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