sgl-project/sglang · critical · ValueError

model_index.json._minimax_h3 must be an object

Error message

model_index.json._minimax_h3 must be an object

What it means

MiniMaxH3ReleaseMetadata.from_model_index requires a mapping (JSON object) under the _minimax_h3 key in model_index.json. If the key is missing (None), a string, a list, or otherwise not a Mapping, config load fails.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/release_metadata.py:60

    return values


@dataclass(frozen=True)
class MiniMaxH3ReleaseMetadata:
    schema_version: int
    partition: str
    tasks: tuple[str, ...]
    task_aliases: Mapping[str, str]
    video_sigma_shift: float
    audio_sigma_shift: float

    @classmethod
    def from_model_index(
        cls, model_index: Mapping[str, Any]
    ) -> MiniMaxH3ReleaseMetadata:
        raw = model_index.get("_minimax_h3")
        if not isinstance(raw, Mapping):
            raise ValueError("model_index.json._minimax_h3 must be an object")
        if raw.get("schema_version") != 1:
            raise ValueError("model_index.json._minimax_h3.schema_version must be 1")
        partition = raw.get("partition")
        if partition not in {"fl2va", "ref2va"}:
            raise ValueError(
                "model_index.json._minimax_h3.partition must be one of " "fl2va, ref2va"
            )
        tasks = _string_list(raw.get("tasks"), "model_index.json._minimax_h3.tasks")
        aliases = raw.get("task_aliases", {})
        if not isinstance(aliases, Mapping) or any(
            not isinstance(key, str)
            or not key
            or not isinstance(value, str)
            or not value
            for key, value in aliases.items()
        ):
            raise ValueError(
                "model_index.json._minimax_h3.task_aliases must map strings to strings"

View on GitHub (pinned to 0132848349)

Solutions

  1. Verify model_index.json is complete and contains an object at _minimax_h3; re-download the release if truncated
  2. If packaging a fine-tune, copy the _minimax_h3 block from the official release
  3. Confirm you're loading a genuine MiniMax H3 release, not the base model

Example fix

// before
{ "t2v": {...} }  // no _minimax_h3

// after
{ "t2v": {...}, "_minimax_h3": {"schema_version": 1, "partition": "fl2va", "tasks": [...]} }
Defensive patterns

Strategy: try-catch

Validate before calling

def has_minimax_block(idx) -> bool:
    from collections.abc import Mapping
    return isinstance(idx.get("_minimax_h3"), Mapping)

Try / catch

try:
    meta = MiniMaxH3ReleaseMetadata.from_model_index(json.load(open(path)))
except ValueError as e:
    fail_deploy(f"invalid model_index.json: {e}")

Prevention

When it happens

Trigger: Loading a checkpoint whose model_index.json lacks the _minimax_h3 section entirely, or has it as a scalar/list; raised in _load_config at startup.

Common situations: Using a base/upstream checkpoint repackaged without the MiniMax H3 metadata, or a partial download that truncated the JSON.

Related errors

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