sgl-project/sglang · error · ValueError

MiniMax H3 model variant must be a non-empty string

Error message

MiniMax H3 model variant must be a non-empty string

What it means

Raised by MiniMaxH3Pipeline.model_subfolder_for_variant when the variant argument is not a string, is empty, or is whitespace-only. The static helper maps semantic variant names (fl2va, ref2va) to checkpoint subfolders and rejects meaningless input before lookup.

Source

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

        if not current_platform.is_rocm():
            missing_media_tools = [
                executable
                for executable in ("ffmpeg", "ffprobe")
                if shutil.which(executable) is None
            ]
            if missing_media_tools:
                raise RuntimeError(
                    "MiniMax H3 requires ffmpeg and ffprobe for media processing "
                    "and validated output delivery; missing executables: "
                    f"{', '.join(missing_media_tools)}. Install the ffmpeg system "
                    "package before starting SGLang."
                )
        super().__init__(*args, **kwargs)

    @staticmethod
    def model_subfolder_for_variant(variant: str) -> str:
        if not isinstance(variant, str) or not variant.strip():
            raise ValueError("MiniMax H3 model variant must be a non-empty string")
        normalized = variant.strip().lower()
        subfolders = {
            "fl2va": "FL2VA",
            "ref2va": "Ref2VA",
        }
        try:
            return subfolders[normalized]
        except KeyError as exc:
            raise ValueError(
                f"unsupported MiniMax H3 model variant {variant!r}; "
                f"supported: {sorted(subfolders)!r}"
            ) from exc

    def _load_config(self):
        model_variant = self.server_args.model_variant
        if model_variant is not None:
            semantic_subfolder = self.model_subfolder_for_variant(model_variant)
            explicit_subfolder = self.server_args.model_subfolder

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a concrete variant such as 'fl2va' or 'ref2va'
2. Skip the call entirely when the variant is unset — the pipeline treats None model_variant as no semantic routing
3. Normalize config inputs: treat empty/whitespace strings as None before invoking the pipeline

Example fix

# before
variant = args.model_variant or ''  # '' reaches the helper
subfolder = MiniMaxH3Pipeline.model_subfolder_for_variant(variant)

# after
variant = (args.model_variant or '').strip() or None
subfolder = MiniMaxH3Pipeline.model_subfolder_for_variant(variant) if variant else None

variant = (getattr(server_args, 'model_variant', None) or '').strip() or None
if variant is not None:
    MiniMaxH3Pipeline.model_subfolder_for_variant(variant)  # dry-run validation

def normalize_variant(v: str | None) -> str | None:
    v = (v or '').strip()
    return v if v else None

When it happens

Trigger: Calling model_subfolder_for_variant(''), model_subfolder_for_variant(' '), or passing None/a non-string (e.g. an argparse default of None leaking through); config files supplying an empty --model-variant string.

Common situations: Launch scripts that always pass --model-variant even when unset, forwarding an empty string; YAML/JSON config with variant: '' treated as a value; None defaults not filtered before the call.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• unsupported MiniMax H3 model variant {variant!r}; supported:
• MiniMax H3 --model-variant and --model-subfolder select diff
• MiniMax H3 loaded checkpoint partition does not match --mode
• fl2va requires first_frame, last_frame, or both
• ref2va requires at least one of reference_image, reference_v

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