sgl-project/sglang · critical · KeyError

Unexpected MiniMax H3 Qwen3-VL checkpoint weight: {name} (ma

Error message

Unexpected MiniMax H3 Qwen3-VL checkpoint weight: {name} (mapped to {param_name})

What it means

load_weights found a checkpoint tensor whose mapped name doesn't correspond to any parameter of the model. This guards against silently dropping weights — an unrecognized tensor almost always means the checkpoint doesn't match the model definition.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/encoders/minimax_h3_qwen3vl.py:407

                f"unexpected hidden shape {list(hidden.shape)}, "
                f"expected {expected_shape}"
            )
        return hidden

    def load_weights(
        self,
        weights: Iterable[tuple[str, torch.Tensor]],
    ) -> set[str]:
        params = dict(self.named_parameters(remove_duplicate=False))
        loaded: set[str] = set()
        for name, loaded_weight in weights:
            name = _map_checkpoint_name(name)
            if not self.should_materialize_checkpoint_weight(name):
                continue
            param_name = name
            param = params.get(param_name)
            if param is None:
                raise KeyError(
                    "Unexpected MiniMax H3 Qwen3-VL checkpoint weight: "
                    f"{name} (mapped to {param_name})"
                )
            weight_loader = getattr(param, "weight_loader", default_weight_loader)
            try:
                can_keep_checkpoint_tensor = bool(
                    getattr(self, "_keep_checkpoint_mapping", False)
                    and weight_loader is default_weight_loader
                    and param.device.type == "cpu"
                    and loaded_weight.device.type == "cpu"
                    and loaded_weight.dtype == param.dtype
                    and tuple(loaded_weight.shape) == tuple(param.shape)
                )
                if can_keep_checkpoint_tensor:
                    param.data = loaded_weight
                else:
                    weight_loader(param, loaded_weight.to(param.dtype))
            except Exception as exc:

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect the reported name and extend _map_checkpoint_name or filter such keys before calling load_weights
2. Verify you're loading the encoder-specific checkpoint shard matching this model class
3. Check for sglang version updates that added new name mappings

Example fix

# before
model.load_weights(iter(weights))
# after
owned = set(dict(model.named_parameters()))
weights = [(n, t) for n, t in weights if _map_checkpoint_name(n) in owned]
model.load_weights(iter(weights))

owned = {n for n, _ in model.named_parameters()}
from sglang.multimodal_gen.runtime.models.encoders.minimax_h3_qwen3vl import _map_checkpoint_name
filtered = [(n, t) for n, t in weights if _map_checkpoint_name(n) in owned]

When it happens

Trigger: load_weights iterating checkpoint weights where _map_checkpoint_name(name) yields a key absent from self.state_dict (via params lookup).

Common situations: Loading a full MiniMax H3 checkpoint that includes non-encoder modules (LM head, vision tower extras) not owned by this encoder; version skew between checkpoint export format and the loader's name mapping.

Related errors

• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• MiniMax H3 pruned curve checkpoints cannot use a separate Ad
• H3 conditioning projection {bias_name} has shape {tuple(bias
• H3 conditioning projection contains unsupported tensors: {so
• Failed to load MiniMax H3 Qwen3-VL weight {name!r}: checkpoi

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