{"record":{"id":"d06535d587d32f3a","repo":"sgl-project/sglang","slug":"gguf-tensor-tensor-name-declares-original-shape","errorCode":null,"errorMessage":"GGUF tensor {tensor.name} declares original shape {logical_shape}, which contains {math.prod(logical_shape)} elements instead of {tensor.n_elements}","messagePattern":"GGUF tensor (.+?) declares original shape (.+?), which contains (.+?) elements instead of (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/loader/gguf_weights.py","lineNumber":96,"sourceCode":"    return reader\n\n\ndef read_gguf_tensor_meta(gguf_file: str) -> dict[str, GGUFTensorMeta]:\n    \"\"\"Read the exact packed shape required by diffusion parameters.\"\"\"\n    gguf = _gguf_module()\n    WeightType = gguf.GGMLQuantizationType\n    reader = _open_reader(gguf_file)\n    metadata: dict[str, GGUFTensorMeta] = {}\n    for tensor in reader.tensors:\n        weight_type = WeightType(tensor.tensor_type)\n        shape_field = reader.fields.get(f\"comfy.gguf.orig_shape.{tensor.name}\")\n        logical_shape = (\n            tuple(int(dim) for dim in shape_field.contents())\n            if shape_field is not None\n            else tuple(int(dim) for dim in reversed(tensor.shape))\n        )\n        if math.prod(logical_shape) != tensor.n_elements:\n            raise ValueError(\n                f\"GGUF tensor {tensor.name} declares original shape \"\n                f\"{logical_shape}, which contains {math.prod(logical_shape)} \"\n                f\"elements instead of {tensor.n_elements}\"\n            )\n        is_quantized = int(weight_type) not in _UNQUANTIZED_TYPES\n        dequantize_on_load = False\n        if is_quantized:\n            if len(logical_shape) != 2 or not tensor.name.endswith(\".weight\"):\n                raise ValueError(\n                    f\"GGUF tensor {tensor.name} is quantized, but diffusion GGUF \"\n                    \"currently supports packed data only for 2D linear .weight \"\n                    \"tensors\"\n                )\n            block_size, type_size = gguf.GGML_QUANT_SIZES[weight_type]\n            inner_dim = logical_shape[-1]\n            if inner_dim % block_size:\n                if shape_field is None:\n                    raise ValueError(","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/loader/gguf_weights.py#L78-L114","documentation":"This error is raised while reading GGUF tensor metadata for diffusion-model weights. The tensor's optional original-shape field (e.g. ComfyUI's shape annotation) declares a logical shape whose element count does not match the number of elements actually stored in the GGUF tensor. Since downstream layout logic (packed rows, dequantization) assumes these agree, the loader rejects the checkpoint rather than guessing.","triggerScenarios":"Calling read_gguf_tensor_meta (directly or via _get_encoder_quant_config / _resolve_gguf_quant_load_spec) on a GGUF file where a tensor has a 'shape' metadata field whose math.prod(shape) != tensor.n_elements. Typically a ComfyUI-exported GGUF whose shape annotation is stale or transposed relative to the stored data.","commonSituations":"Using a ComfyUI diffusion GGUF that was re-quantized or re-packed with shape fields from a different base model; hand-edited GGUF metadata; GGUF files produced by tools that write shapes in a different order than the loader expects when no shape field exists (this only fires when the field IS present).","solutions":["Re-export or re-download the GGUF checkpoint so shape annotations match the stored tensor data","Verify with gguf-py or `gguf_reader` that tensor.n_elements equals the product of the declared shape; if the shape is simply transposed, fix the export tool's shape ordering","If the annotation is wrong and the raw shape is correct, strip the tensor's shape field from the GGUF metadata so the loader falls back to reversed(tensor.shape)"],"exampleFix":"# before: checkpoint has shape field [320, 4, 3, 3] but 11520 stored elements -> mismatch\n# after: fix annotation or remove it\nreader = gguf.GGUFReader(path)\nt = reader.tensors[0]\nassert math.prod(t.shape) == t.n_elements  # keep export tool honest","handlingStrategy":"validation","validationCode":"import gguf, math\nreader = gguf.GGUFReader(path)\nfor t in reader.tensors:\n    field = reader.get_field(f'{t.name}.shape')\n    logical = tuple(int(d) for d in field.contents()) if field else tuple(reversed(t.shape))\n    assert math.prod(logical) == t.n_elements, (t.name, logical, t.n_elements)","typeGuard":"def has_consistent_shape(t, field) -> bool:\n    logical = tuple(int(d) for d in field.contents()) if field is not None else tuple(reversed(t.shape))\n    return math.prod(logical) == t.n_elements","tryCatchPattern":"try:\n    meta = read_gguf_tensor_meta(reader, t)\nexcept ValueError as e:\n    if 'elements instead of' in str(e):\n        raise CheckpointCorruptionError(t.name) from e\n    raise","preventionTips":["Validate GGUF shape annotations right after download","Keep export tool and loader versions in sync","Checksum-verify downloaded GGUF files before loading"],"tags":["gguf","checkpoint","tensor-shape","validation","diffusion"],"backgroundTag":"checkpoint-metadata-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}