{"record":{"id":"5cfae8684bd8e61d","repo":"sgl-project/sglang","slug":"minimax-h3-ring-size-must-be-positive","errorCode":null,"errorMessage":"MiniMax H3 ring size must be positive.","messagePattern":"MiniMax H3 ring size must be positive\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py","lineNumber":1841,"sourceCode":"        ):\n            if value % tp_size:\n                raise ValueError(\n                    f\"MiniMax H3 {name}={value} must be divisible by \"\n                    f\"TP size {tp_size}.\"\n                )\n\n    @staticmethod\n    def _validate_sequence_parallel_config(\n        *,\n        arch: MiniMaxH3DiTArchConfig,\n        tp_size: int,\n        ulysses_size: int,\n        ring_size: int,\n    ) -> None:\n        if ulysses_size <= 0:\n            raise ValueError(\"MiniMax H3 Ulysses size must be positive.\")\n        if ring_size <= 0:\n            raise ValueError(\"MiniMax H3 ring size must be positive.\")\n        local_heads = arch.num_attention_heads // tp_size\n        if local_heads % ulysses_size:\n            raise ValueError(\n                f\"MiniMax H3 TP-local heads {local_heads} must be divisible by \"\n                f\"Ulysses size {ulysses_size} (total heads=\"\n                f\"{arch.num_attention_heads}, TP={tp_size}).\"\n            )\n        # ring never shards heads (only rows), so it has no head-divisibility\n        # constraint; the packed sequence alignment constant must still\n        # divide the *combined* sequence-parallel size, since ring adds an\n        # outer row split on top of Ulysses's inner one (see forward()).\n        sp_size = ulysses_size * ring_size\n        if MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT % sp_size:\n            raise ValueError(\n                \"MiniMax H3 packed sequence alignment \"\n                f\"{MINIMAX_H3_PACKED_SEQUENCE_ALIGNMENT} must be divisible by \"\n                f\"the combined sequence-parallel size {sp_size} \"\n                f\"(ulysses={ulysses_size} x ring={ring_size}). Choose degrees \"","sourceCodeStart":1823,"sourceCodeEnd":1859,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py#L1823-L1859","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use ring_size=1 to disable ring attention, or a positive value whose product with ulysses divides the packed alignment constant","Fix flag defaults: missing/empty → 1","Double-check the combined sp_size = ulysses * ring against the alignment constraint"],"exampleFix":"# before\nring_size=0\n# after\nring_size=1  # ring attention disabled","handlingStrategy":"validation","validationCode":"ring_size = int(os.getenv(\"RING\") or 1)\nassert ring_size >= 1","typeGuard":"def ring_ok(r: int) -> bool:\n    return isinstance(r, int) and r >= 1","tryCatchPattern":null,"preventionTips":["Use 1 (not 0) to disable ring attention","Keep ulysses/ring flag semantics documented in launch scripts"],"tags":["ring-attention","sequence-parallel","config","validation"],"backgroundTag":"invalid-parallelism-config","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}