{"record":{"id":"b7f19ad73feef60f","repo":"Comfy-Org/ComfyUI","slug":"nvfp4-requires-2d-tensor-got-tensor-dim-d","errorCode":null,"errorMessage":"NVFP4 requires 2D tensor, got {tensor.dim()}D","messagePattern":"NVFP4 requires 2D tensor, got (.+?)D","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy/quant_ops.py","lineNumber":178,"sourceCode":"\n        if stochastic_rounding > 0:\n            qdata, block_scale = comfy.float.stochastic_round_quantize_mxfp8_by_block(tensor, pad_32x=needs_padding, seed=stochastic_rounding)\n        else:\n            qdata, block_scale = ck.quantize_mxfp8(tensor, pad_32x=needs_padding)\n\n        params = cls.Params(\n            scale=block_scale,\n            orig_dtype=orig_dtype,\n            orig_shape=orig_shape,\n        )\n        return qdata, params\n\n\nclass TensorCoreNVFP4Layout(_CKNvfp4Layout):\n    @classmethod\n    def quantize(cls, tensor, scale=None, stochastic_rounding=0, inplace_ops=False):\n        if tensor.dim() != 2:\n            raise ValueError(f\"NVFP4 requires 2D tensor, got {tensor.dim()}D\")\n\n        orig_dtype = tensor.dtype\n        orig_shape = tuple(tensor.shape)\n\n        if scale is None or (isinstance(scale, str) and scale == \"recalculate\"):\n            scale = torch.amax(tensor.abs()) / (ck.float_utils.F8_E4M3_MAX * ck.float_utils.F4_E2M1_MAX)\n\n        if not isinstance(scale, torch.Tensor):\n            scale = torch.tensor(scale)\n        scale = scale.to(device=tensor.device, dtype=torch.float32)\n\n        padded_shape = cls.get_padded_shape(orig_shape)\n        needs_padding = padded_shape != orig_shape\n\n        if stochastic_rounding > 0:\n            qdata, block_scale = comfy.float.stochastic_round_quantize_nvfp4_by_block(tensor, scale, pad_16x=needs_padding, seed=stochastic_rounding)\n        else:\n            qdata, block_scale = ck.quantize_nvfp4(tensor, scale, pad_16x=needs_padding)","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/quant_ops.py#L160-L196","documentation":"TensorCoreNVFP4Layout.quantize in comfy/quant_ops.py raises when the input tensor is not 2D. NVFP4 uses a 2D block-scale grid (typically 16-element groups over a flattened [N, K] matrix); a tensor of any other rank cannot be assigned a valid block layout, so quantization is rejected up front.","triggerScenarios":"Passing a Conv weight (4D), norm/bias vector (1D), or embedding tensor to TensorCoreNVFP4Layout.quantize; quantizing weights that an adapter reshaped to 3D; blanket quantization loops that hit every parameter.","commonSituations":"Quantization scripts that walk all model parameters instead of Linear layers only; attempting NVFP4 on CNNs or models with fused attention weights carrying extra dims; tensors with a leftover batch/head dimension.","solutions":["Restrict NVFP4 quantization to 2D nn.Linear weight matrices.","Guard the call: skip tensors with tensor.dim() != 2 and leave them in higher precision.","Reshape 4D conv weights to [out, in*kh*kw] only if the corresponding dequantize path restores the original shape via orig_shape."],"exampleFix":"# before\nqdata, params = TensorCoreNVFP4Layout.quantize(weight)  # crashes on 4D\n\n# after\nif weight.dim() == 2:\n    qdata, params = TensorCoreNVFP4Layout.quantize(weight)\nelse:\n    qdata, params = weight, None  # keep unquantized","handlingStrategy":"type-guard","validationCode":"if tensor.dim() != 2:\n    raise ValueError(f'skip NVFP4 for {tensor.dim()}D tensor; quantize only Linear weights')","typeGuard":"def is_nvfp4_quantizable(t: torch.Tensor) -> bool:\n    return isinstance(t, torch.Tensor) and t.dim() == 2 and t.is_floating_point()","tryCatchPattern":null,"preventionTips":["Only send 2D weight matrices to NVFP4 quantization.","Log the shapes of tensors you intend to quantize before running a batch quantization job."],"tags":["quantization","nvfp4","shape-validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}