sgl-project/sglang · error · ValueError

MiniMax H3 loaded checkpoint partition does not match --mode

Error message

MiniMax H3 loaded checkpoint partition does not match --model-variant {model_variant!r}

What it means

Raised by MiniMaxH3Pipeline._load_config when the partition recorded in the checkpoint's model_index metadata (MiniMaxH3ReleaseMetadata.from_model_index) disagrees with the requested --model-variant. This is a post-load integrity check: it catches checkpoints whose actual weights partition differs from what the user asked for.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines/minimax_h3_pipeline.py:109

            explicit_subfolder = self.server_args.model_subfolder
            if (
                explicit_subfolder is not None
                and explicit_subfolder.strip().lower() != semantic_subfolder.lower()
            ):
                raise ValueError(
                    "MiniMax H3 --model-variant and --model-subfolder select "
                    f"different weight partitions: variant={model_variant!r} maps to "
                    f"{semantic_subfolder!r}, model_subfolder="
                    f"{explicit_subfolder!r}"
                )
            self.server_args.model_subfolder = semantic_subfolder
        model_index = super()._load_config()
        self.release_metadata = MiniMaxH3ReleaseMetadata.from_model_index(model_index)
        if (
            model_variant is not None
            and self.release_metadata.partition != model_variant.strip().lower()
        ):
            raise ValueError(
                "MiniMax H3 loaded checkpoint partition does not match "
                f"--model-variant {model_variant!r}"
            )
        return model_index

    def validate_disagg_role(self, role: RoleType) -> None:
        if role != RoleType.MONOLITHIC:
            raise ValueError(
                "MiniMaxH3Pipeline only supports monolithic deployment; "
                f"disaggregation role {role.value!r} is not supported"
            )

    def create_pipeline_stages(self, server_args: ServerArgs) -> None:
        # Per-model sigma override from model_index.json; contract tests
        # construct the pipeline without model_path, hence the guard.
        release_metadata = getattr(self, "release_metadata", None)
        sigma_shift_scales = (
            release_metadata.sigma_shift_scales

View on GitHub (pinned to 0132848349)

Solutions

1. Point --model-path at the checkpoint matching your variant, or change --model-variant to the partition the checkpoint actually contains (see its model_index metadata)
2. If the directory was assembled manually, restore the correct model_index.json/weights for the intended partition or re-download the official snapshot
3. Log MiniMaxH3ReleaseMetadata.from_model_index(model_index).partition during debugging to see the ground truth

Example fix

# before
--model-path /models/minimax-h3-ref2va --model-variant fl2va

# after
--model-path /models/minimax-h3-ref2va --model-variant ref2va

from sglang.multimodal_gen.runtime.pipelines.minimax_h3_pipeline import MiniMaxH3ReleaseMetadata
import json, pathlib
mi = json.loads(pathlib.Path(model_path, 'model_index.json').read_text())
part = MiniMaxH3ReleaseMetadata.from_model_index(mi).partition
if server_args.model_variant and part != server_args.model_variant.strip().lower():
    raise SystemExit(f'checkpoint is {part!r}; fix --model-variant or --model-path')

When it happens

Trigger: --model-variant fl2va pointing at a Ref2VA-only checkpoint (or vice versa); a local directory whose contents were swapped/re-uploaded under the wrong name; a fine-tuned copy that inherited another partition's model_index.json.

Common situations: Renamed or re-sharded local model dirs; mixed-artifact directories assembled from multiple downloads; checkpoint repos hosting both partitions in one tree.

Related errors

• MiniMax H3 model variant must be a non-empty string
• unsupported MiniMax H3 model variant {variant!r}; supported:
• MiniMax H3 --model-variant and --model-subfolder select diff
• --model-variant {server_args.model_variant} requires '{cls._
• MiniMax H3 requires ffmpeg and ffprobe for media processing

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