sgl-project/sglang · error · ValueError

MiniMax-H3 NVFP4 metadata requires checkpoint files

Error message

MiniMax-H3 NVFP4 metadata requires checkpoint files

What it means

Building the NVFP4 QuantizationConfig requires reading scale/metadata tensors directly from the safetensors files. If layer markers indicate NVFP4 but no safetensors file list was passed to resolve_minimax_h3_checkpoint_quantization, the config cannot be constructed and the loader raises.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/minimax_h3_weights.py:67

    return adaln_curve_shape, layer_markers


def resolve_minimax_h3_checkpoint_quantization(
    layer_markers: dict[str, dict[str, Any]],
    safetensors_list: list[str] | None = None,
    param_names_mapping: dict | None = None,
    reverse_param_names_mapping: dict | None = None,
) -> QuantizationConfig | None:
    formats = {str(marker.get("format")) for marker in layer_markers.values()}
    if "nvfp4" in formats:
        unsupported = formats - {"nvfp4", "int8_tensorwise", "float8_e4m3fn"}
        if unsupported:
            raise NotImplementedError(
                "Unsupported Comfy NVFP4 companion format(s): "
                + ", ".join(sorted(unsupported))
            )
        if safetensors_list is None:
            raise ValueError("MiniMax-H3 NVFP4 metadata requires checkpoint files")
        config = build_nvfp4_config_from_safetensors_list(
            safetensors_list,
            param_names_mapping,
            reverse_param_names_mapping,
        )
        if not isinstance(config, ModelOptFp4Config):
            raise ValueError("Could not resolve MiniMax-H3 NVFP4 checkpoint layout")
        config.set_comfy_layer_markers(layer_markers)
        config.checkpoint_uses_comfy_quantization = True
        config.checkpoint_uses_native_qkv_layout = True
        config.checkpoint_weight_scale_layout = "swizzled"
        config.swap_weight_nibbles = True
        return config
    return resolve_comfy_checkpoint_quantization(layer_markers)


def validate_minimax_h3_checkpoint_variant(
    checkpoint_paths: list[str], selected_variant: str

View on GitHub (pinned to 0132848349)

Solutions

1. Pass the full safetensors file list to resolve_minimax_h3_checkpoint_quantization whenever markers may contain nvfp4
2. Prefer going through load_customized, which wires the file list automatically
3. Guard before calling: if any marker format is 'nvfp4', assert safetensors_list is not None

Example fix

# before: resolve_minimax_h3_checkpoint_quantization(markers, None, mapping, rev_mapping)  # nvfp4 present -> raise
# after: resolve_minimax_h3_checkpoint_quantization(markers, safetensors_list, mapping, rev_mapping)

formats = {str(m.get('format')) for m in layer_markers.values()}
if 'nvfp4' in formats:
    assert safetensors_list, 'NVFP4 markers require the safetensors file list'

def can_resolve(markers: dict, safetensors_list) -> bool:
    formats = {str(m.get('format')) for m in markers.values()}
    return 'nvfp4' not in formats or safetensors_list is not None

try:
    q = resolve_minimax_h3_checkpoint_quantization(markers, files, mapping, rev)
except ValueError as e:
    if 'requires checkpoint files' in str(e):
        raise ConfigError('pass safetensors_list for NVFP4 checkpoints') from e
    raise

When it happens

Trigger: Calling resolve_minimax_h3_checkpoint_quantization with layer_markers containing 'nvfp4' but safetensors_list=None. In normal loading this should not happen; it occurs when callers inspect markers separately and then call the resolver without forwarding the file list.

Common situations: Custom loading pipelines that split metadata inspection from file loading and forget to pass safetensors_list; testing the resolver with synthetic markers only; refactors that dropped the argument.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• comfy_nvfp4 is inferred from per-layer checkpoint metadata;
• Unsupported Comfy NVFP4 companion format(s): + ", ".join(sor
• MiniMaxH3DiTModel.forward requires kwarg {key!r}
• server_args is required to resolve Ideogram4 NVFP4 paths
• must provide either a lambda or static kwargs

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