sgl-project/sglang · critical · ValueError

MiniMax H3 ring size must be positive.

Error message

MiniMax H3 ring size must be positive.

What it means

The ring-attention sequence-parallel degree must be positive. Ring attention adds an outer row split over the packed sequence; a zero/negative ring size invalidates local row counts and is rejected during construction.

Source

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

        ):
            if value % tp_size:
                raise ValueError(
                    f"MiniMax H3 {name}={value} must be divisible by "
                    f"TP size {tp_size}."
                )

    @staticmethod
    def _validate_sequence_parallel_config(
        *,
        arch: MiniMaxH3DiTArchConfig,
        tp_size: int,
        ulysses_size: int,
        ring_size: int,
    ) -> None:
        if ulysses_size <= 0:
            raise ValueError("MiniMax H3 Ulysses size must be positive.")
        if ring_size <= 0:
            raise ValueError("MiniMax H3 ring size must be positive.")
        local_heads = arch.num_attention_heads // tp_size
        if local_heads % ulysses_size:
            raise ValueError(
                f"MiniMax H3 TP-local heads {local_heads} must be divisible by "
                f"Ulysses size {ulysses_size} (total heads="
                f"{arch.num_attention_heads}, TP={tp_size})."
            )
        # ring never shards heads (only rows), so it has no head-divisibility
        # constraint; the packed sequence alignment constant must still
        # divide the *combined* sequence-parallel size, since ring adds an
        # outer row split on top of Ulysses's inner one (see forward()).
        sp_size = ulysses_size * ring_size
        if MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT % sp_size:
            raise ValueError(
                "MiniMax H3 packed sequence alignment "
                f"{MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT} must be divisible by "
                f"the combined sequence-parallel size {sp_size} "
                f"(ulysses={ulysses_size} x ring={ring_size}). Choose degrees "

View on GitHub (pinned to 0132848349)

Solutions

1. Use ring_size=1 to disable ring attention, or a positive value whose product with ulysses divides the packed alignment constant
2. Fix flag defaults: missing/empty → 1
3. Double-check the combined sp_size = ulysses * ring against the alignment constraint

Example fix

# before
ring_size=0
# after
ring_size=1  # ring attention disabled

ring_size = int(os.getenv("RING") or 1)
assert ring_size >= 1

def ring_ok(r: int) -> bool:
    return isinstance(r, int) and r >= 1

When it happens

Trigger: Constructing the model with ring_size=0 or negative, e.g. from a CLI/env default or a computed value like ulysses_size // world that hit zero.

Common situations: Ring attention disabled via 0 instead of 1; env var parsing that maps missing to 0; mismatch between ulysses and ring flags after a rename.

Related errors

• MiniMax H3 Ulysses size must be positive.
• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head
• f"Unknown feature map: {feature_map}"
• f"Unsupported patch_size type: {type(patch_size)}"

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