{"record":{"id":"c8e5deb4f850130d","repo":"sgl-project/sglang","slug":"unsupported-comfy-nvfp4-companion-format-s","errorCode":null,"errorMessage":"Unsupported Comfy NVFP4 companion format(s): + \", \".join(sorted(unsupported))","messagePattern":"Unsupported Comfy NVFP4 companion format\\(s\\): \\+ \", \"\\.join\\(sorted\\(unsupported\\)\\)","errorType":"validation","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/loader/minimax_h3_weights.py","lineNumber":62,"sourceCode":"                        \"MiniMax-H3 checkpoint shards disagree on adaln_t_table \"\n                        f\"shape: {adaln_curve_shape} vs {shape}\"\n                    )\n                adaln_curve_shape = shape\n\n    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","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/loader/minimax_h3_weights.py#L44-L80","documentation":"When a MiniMax-H3 checkpoint's layer markers (from quantization metadata) include the 'nvfp4' format, the resolver only accepts 'nvfp4', 'int8_tensorwise', and 'float8_e4m3fn' as companion per-layer formats. Any other format appearing alongside NVFP4 is not implemented and raises NotImplementedError.","triggerScenarios":"Calling resolve_minimax_h3_checkpoint_quantization (via load_customized) on a checkpoint whose serialized layer markers mix 'nvfp4' with formats like 'int4', 'awq', 'fp8_dynamic', or unknown strings.","commonSituations":"ComfyUI NVFP4 exports that also quantize some layers with a different scheme; checkpoints converted by third-party tools that emit nonstandard format marker strings; partially requantized NVFP4 checkpoints.","solutions":["Re-quantize so companion layers use only int8_tensorwise or float8_e4m3fn alongside nvfp4","Check the marker strings in the checkpoint metadata to find which layers carry the unsupported format and leave those unquantized or int8","Use a prebuilt NVFP4 checkpoint distribution known to be compatible"],"exampleFix":"# before: markers = {'layers.0': {'format': 'nvfp4'}, 'layers.3': {'format': 'q4k'}} -> NotImplementedError\n# after: markers['layers.3'] = {'format': 'int8_tensorwise'}","handlingStrategy":"type-guard","validationCode":"ALLOWED = {'nvfp4', 'int8_tensorwise', 'float8_e4m3fn'}\nformats = {str(m.get('format')) for m in layer_markers.values()}\nif 'nvfp4' in formats:\n    bad = formats - ALLOWED\n    assert not bad, f'unsupported companion formats: {sorted(bad)}'","typeGuard":"def nvfp4_markers_supported(layer_markers: dict) -> bool:\n    formats = {str(m.get('format')) for m in layer_markers.values()}\n    return 'nvfp4' not in formats or formats <= {'nvfp4', 'int8_tensorwise', 'float8_e4m3fn'}","tryCatchPattern":"try:\n    q = resolve_minimax_h3_checkpoint_quantization(markers, files, mapping, rev)\nexcept NotImplementedError as e:\n    if 'NVFP4 companion' in str(e):\n        raise UnsupportedQuantMix(sorted({str(m.get('format')) for m in markers.values()})) from e\n    raise","preventionTips":["Use exporter presets limited to the three supported companion formats","Log all distinct layer formats before loading","Pin checkpoint versions validated against the loader"],"tags":["minimax-h3","nvfp4","quantization","unsupported-format"],"backgroundTag":"unsupported-quantization-format","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}