What causes "Missing NVFP4 scales for layer {layer_name}" in Comfy-Org/ComfyUI?

Inspect the checkpoint keys (e.g. torch.load / safetensors keys) for ` .weight_scale` and ` .weight_scale_2` and confirm both exist next to ` .weight` and ` .comfy_quant`.

Comfy-Org/ComfyUI · critical · ValueError

Missing NVFP4 scales for layer {layer_name}

Error message

Missing NVFP4 scales for layer {layer_name}

What it means

Raised by _load_quantized_module in comfy/ops.py when a layer's `comfy_quant` metadata declares quant_format 'nvfp4' but the state dict does not contain both `weight_scale_2` (the per-tensor secondary scale) and `weight_scale` (the fp8-e4m3 block scale). NVFP4 quantization needs both scales to reconstruct weight values, so loading aborts. The error names the exact layer so you can find which Linear/Conv is missing keys.

Source

Thrown at comfy/ops.py:1174

            raise ValueError(f"Unknown quantization format for layer {layer_name}")

        qconfig = QUANT_ALGOS[module.quant_format]
        module.layout_type = qconfig["comfy_tensor_layout"]
        layout_cls = get_layout_class(module.layout_type)

        # Per-format scales; fp8 dtype views handle both legacy uint8-on-disk and native fp8.
        if module.quant_format in ("float8_e4m3fn", "float8_e5m2"):
            scales = {"scale": pop_scale("weight_scale")}
        elif module.quant_format == "mxfp8":
            bs = pop_scale("weight_scale", torch.float8_e8m0fnu)
            if bs is None:
                raise ValueError(f"Missing MXFP8 block scales for layer {layer_name}")
            scales = {"scale": bs}
        elif module.quant_format == "nvfp4":
            ts = pop_scale("weight_scale_2")
            bs = pop_scale("weight_scale", torch.float8_e4m3fn)
            if ts is None or bs is None:
                raise ValueError(f"Missing NVFP4 scales for layer {layer_name}")
            scales = {"scale": ts, "block_scale": bs}
        elif module.quant_format == "int8_tensorwise":
            scale = pop_scale("weight_scale")
            if scale is None:
                raise ValueError(f"Missing INT8 weight scale for layer {layer_name}")
            scales = {"scale": scale}
            params_conf = layer_conf.get("params", {})
            if not isinstance(params_conf, dict):
                params_conf = {}
            if layer_conf.get("convrot", params_conf.get("convrot", False)):
                scales["convrot"] = True
                scales["convrot_groupsize"] = int(
                    layer_conf.get("convrot_groupsize", params_conf.get("convrot_groupsize", 256))
                )
        elif module.quant_format == "convrot_w4a4":
            scale = pop_scale("weight_scale")
            if scale is None:
                raise ValueError(f"Missing ConvRot W4A4 weight scale for layer {layer_name}")

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Inspect the checkpoint keys (e.g. torch.load / safetensors keys) for `<layer_prefix>.weight_scale` and `<layer_prefix>.weight_scale_2` and confirm both exist next to `<layer_prefix>.weight` and `<layer_prefix>.comfy_quant`.
Re-quantize the model with ComfyUI's own quantization path so both NVFP4 scales are emitted with the expected key names.
Re-download the quantized checkpoint in case the file is truncated or a shard is missing.
If the scales genuinely cannot be supplied, dequantize the layer back to fp16/bf16 or drop the `comfy_quant` entry so it loads as a plain dense layer.

Example fix

# before: state dict has only
# model.layers.0.self_attn.q_proj.weight
# model.layers.0.self_attn.q_proj.comfy_quant
# (missing weight_scale / weight_scale_2 -> ValueError)

# after: include both scales
# model.layers.0.self_attn.q_proj.weight
# model.layers.0.self_attn.q_proj.weight_scale       # fp8 e4m3 block scale
# model.layers.0.self_attn.q_proj.weight_scale_2     # per-tensor scale
# model.layers.0.self_attn.q_proj.comfy_quant

Defensive patterns

Strategy: validation

Validate before calling

prefix = 'model.layers.0.self_attn.q_proj.'
need = {prefix + 'weight_scale_2', prefix + 'weight_scale'}
missing = need - set(sd.keys())
assert not missing, f'NVFP4 layer missing scales: {missing}'

Try / catch

try:
    model_patcher = load_diffusion_model(path)
except ValueError as e:
    if 'Missing NVFP4 scales' in str(e):
        raise SystemExit(f'{path} is an incomplete NVFP4 quantization; re-quantize or re-download')
    raise

Prevention

Quantize models only with ComfyUI's own quantization utilities so scale key names always match the loader.
When merging or filtering state dicts, never drop keys named weight_scale, weight_scale_2, weight_s_rel.
After downloading a quantized checkpoint, verify scale keys exist before loading.

When it happens

Trigger: Loading a GGUF/safetensors checkpoint that was quantized to NVFP4 where `comfy_quant` config is present but `weight_scale` or `weight_scale_2` keys were stripped, renamed, or saved under a different prefix; merging a state dict that only carries the quantized weight tensor; partially sharded checkpoints where scale shards were not concatenated.

Common situations: Using an external NVFP4 conversion tool that does not emit ComfyUI's expected scale key names; hand-editing or re-saving quantized checkpoints; downloading an incomplete/corrupted quantized model; checkpoints quantized with a newer/older key naming convention.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/6dc7f6791afd3d61. Report an issue: GitHub.