{"record":{"id":"ef2fc5bda14b3a2a","repo":"sgl-project/sglang","slug":"minimax-h3-nvfp4-metadata-requires-checkpoint-file","errorCode":null,"errorMessage":"MiniMax-H3 NVFP4 metadata requires checkpoint files","messagePattern":"MiniMax-H3 NVFP4 metadata requires checkpoint files","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/loader/minimax_h3_weights.py","lineNumber":67,"sourceCode":"    return adaln_curve_shape, layer_markers\n\n\ndef resolve_minimax_h3_checkpoint_quantization(\n    layer_markers: dict[str, dict[str, Any]],\n    safetensors_list: list[str] | None = None,\n    param_names_mapping: dict | None = None,\n    reverse_param_names_mapping: dict | None = None,\n) -> QuantizationConfig | None:\n    formats = {str(marker.get(\"format\")) for marker in layer_markers.values()}\n    if \"nvfp4\" in formats:\n        unsupported = formats - {\"nvfp4\", \"int8_tensorwise\", \"float8_e4m3fn\"}\n        if unsupported:\n            raise NotImplementedError(\n                \"Unsupported Comfy NVFP4 companion format(s): \"\n                + \", \".join(sorted(unsupported))\n            )\n        if safetensors_list is None:\n            raise ValueError(\"MiniMax-H3 NVFP4 metadata requires checkpoint files\")\n        config = build_nvfp4_config_from_safetensors_list(\n            safetensors_list,\n            param_names_mapping,\n            reverse_param_names_mapping,\n        )\n        if not isinstance(config, ModelOptFp4Config):\n            raise ValueError(\"Could not resolve MiniMax-H3 NVFP4 checkpoint layout\")\n        config.set_comfy_layer_markers(layer_markers)\n        config.checkpoint_uses_comfy_quantization = True\n        config.checkpoint_uses_native_qkv_layout = True\n        config.checkpoint_weight_scale_layout = \"swizzled\"\n        config.swap_weight_nibbles = True\n        return config\n    return resolve_comfy_checkpoint_quantization(layer_markers)\n\n\ndef validate_minimax_h3_checkpoint_variant(\n    checkpoint_paths: list[str], selected_variant: str","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/loader/minimax_h3_weights.py#L49-L85","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the full safetensors file list to resolve_minimax_h3_checkpoint_quantization whenever markers may contain nvfp4","Prefer going through load_customized, which wires the file list automatically","Guard before calling: if any marker format is 'nvfp4', assert safetensors_list is not None"],"exampleFix":"# before: resolve_minimax_h3_checkpoint_quantization(markers, None, mapping, rev_mapping)  # nvfp4 present -> raise\n# after: resolve_minimax_h3_checkpoint_quantization(markers, safetensors_list, mapping, rev_mapping)","handlingStrategy":"type-guard","validationCode":"formats = {str(m.get('format')) for m in layer_markers.values()}\nif 'nvfp4' in formats:\n    assert safetensors_list, 'NVFP4 markers require the safetensors file list'","typeGuard":"def can_resolve(markers: dict, safetensors_list) -> bool:\n    formats = {str(m.get('format')) for m in markers.values()}\n    return 'nvfp4' not in formats or safetensors_list is not None","tryCatchPattern":"try:\n    q = resolve_minimax_h3_checkpoint_quantization(markers, files, mapping, rev)\nexcept ValueError as e:\n    if 'requires checkpoint files' in str(e):\n        raise ConfigError('pass safetensors_list for NVFP4 checkpoints') from e\n    raise","preventionTips":["Always forward the full safetensors list through custom load paths","Prefer load_customized over calling the resolver directly","Add a fast unit test asserting the resolver signature contract"],"tags":["minimax-h3","nvfp4","missing-argument","api-misuse"],"backgroundTag":"missing-required-parameter","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}