{"record":{"id":"b3f214f09c0482d4","repo":"Comfy-Org/ComfyUI","slug":"mxfp8-requires-2d-tensor-got-tensor-dim-d","errorCode":null,"errorMessage":"MXFP8 requires 2D tensor, got {tensor.dim()}D","messagePattern":"MXFP8 requires 2D tensor, got (.+?)D","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy/quant_ops.py","lineNumber":153,"sourceCode":"\n        if stochastic_rounding > 0:\n            if inplace_ops:\n                tensor *= (1.0 / scale).to(tensor.dtype)\n            else:\n                tensor = tensor * (1.0 / scale).to(tensor.dtype)\n            qdata = comfy.float.stochastic_rounding(tensor, dtype=cls.FP8_DTYPE, seed=stochastic_rounding)\n        else:\n            qdata = ck.quantize_per_tensor_fp8(tensor, scale, cls.FP8_DTYPE)\n\n        params = cls.Params(scale=scale.float(), orig_dtype=orig_dtype, orig_shape=orig_shape)\n        return qdata, params\n\n\nclass TensorCoreMXFP8Layout(_CKMxfp8Layout):\n    @classmethod\n    def quantize(cls, tensor, scale=None, stochastic_rounding=0, inplace_ops=False):\n        if tensor.dim() != 2:\n            raise ValueError(f\"MXFP8 requires 2D tensor, got {tensor.dim()}D\")\n\n        orig_dtype = tensor.dtype\n        orig_shape = tuple(tensor.shape)\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_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","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/quant_ops.py#L135-L171","documentation":"TensorCoreMXFP8Layout.quantize in comfy/quant_ops.py rejects any tensor that is not exactly 2D. MXFP8 stores block scales on a 32x32 2D grid over (out_channels, in_channels), so 1D biases, 3D conv weights, or 4D tensors have no valid block layout and quantization fails fast rather than silently mis-shaping scales.","triggerScenarios":"Calling TensorCoreMXFP8Layout.quantize on a Conv weight (4D), an embedding/norm tensor (1D/3D), or any tensor produced after an unsolicited reshape; quantizing a model whose Linear weights were transposed to 3D by an adapter.","commonSituations":"Model-quantization scripts that iterate all parameters instead of only nn.Linear weights; trying to apply MXFP8 to conv-heavy architectures; passing a fused/qkv tensor with an extra head dimension.","solutions":["Only route 2D nn.Linear weight matrices to the MXFP8 quantizer; skip norms, biases, embeddings and conv weights.","If quantizing a conv, first reshape to 2D ([out, in*kh*kw]) only if your kernel path supports dequantizing back to 4D.","Check for accidental unsqueeze/squeeze upstream that changed rank before quantize() was called."],"exampleFix":"# before\nTensorCoreMXFP8Layout.quantize(conv.weight)  # 4D -> ValueError\n\n# after\nfor name, module in model.named_modules():\n    if isinstance(module, torch.nn.Linear):\n        q, p = TensorCoreMXFP8Layout.quantize(module.weight)","handlingStrategy":"type-guard","validationCode":"if tensor.dim() != 2:\n    raise ValueError(f'skip MXFP8 for {tensor.dim()}D tensor; quantize only Linear weights')","typeGuard":"def is_mxfp8_quantizable(t: torch.Tensor) -> bool:\n    return isinstance(t, torch.Tensor) and t.dim() == 2 and t.is_floating_point()","tryCatchPattern":null,"preventionTips":["Quantization loops should filter on isinstance(module, torch.nn.Linear) rather than all parameters.","Keep conv, norm, bias and embedding tensors out of MXFP8 quantization sets."],"tags":["quantization","mxfp8","shape-validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}