sgl-project/sglang · error · ValueError

GGUF tensor {tensor.name} declares original shape {logical_s

Error message

GGUF tensor {tensor.name} declares original shape {logical_shape}, which contains {math.prod(logical_shape)} elements instead of {tensor.n_elements}

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/gguf_weights.py:96

    return reader


def read_gguf_tensor_meta(gguf_file: str) -> dict[str, GGUFTensorMeta]:
    """Read the exact packed shape required by diffusion parameters."""
    gguf = _gguf_module()
    WeightType = gguf.GGMLQuantizationType
    reader = _open_reader(gguf_file)
    metadata: dict[str, GGUFTensorMeta] = {}
    for tensor in reader.tensors:
        weight_type = WeightType(tensor.tensor_type)
        shape_field = reader.fields.get(f"comfy.gguf.orig_shape.{tensor.name}")
        logical_shape = (
            tuple(int(dim) for dim in shape_field.contents())
            if shape_field is not None
            else tuple(int(dim) for dim in reversed(tensor.shape))
        )
        if math.prod(logical_shape) != tensor.n_elements:
            raise ValueError(
                f"GGUF tensor {tensor.name} declares original shape "
                f"{logical_shape}, which contains {math.prod(logical_shape)} "
                f"elements instead of {tensor.n_elements}"
            )
        is_quantized = int(weight_type) not in _UNQUANTIZED_TYPES
        dequantize_on_load = False
        if is_quantized:
            if len(logical_shape) != 2 or not tensor.name.endswith(".weight"):
                raise ValueError(
                    f"GGUF tensor {tensor.name} is quantized, but diffusion GGUF "
                    "currently supports packed data only for 2D linear .weight "
                    "tensors"
                )
            block_size, type_size = gguf.GGML_QUANT_SIZES[weight_type]
            inner_dim = logical_shape[-1]
            if inner_dim % block_size:
                if shape_field is None:
                    raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

  1. Re-export or re-download the GGUF checkpoint so shape annotations match the stored tensor data
  2. 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
  3. 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)

Example fix

# before: checkpoint has shape field [320, 4, 3, 3] but 11520 stored elements -> mismatch
# after: fix annotation or remove it
reader = gguf.GGUFReader(path)
t = reader.tensors[0]
assert math.prod(t.shape) == t.n_elements  # keep export tool honest
Defensive patterns

Strategy: validation

Validate before calling

import gguf, math
reader = gguf.GGUFReader(path)
for t in reader.tensors:
    field = reader.get_field(f'{t.name}.shape')
    logical = tuple(int(d) for d in field.contents()) if field else tuple(reversed(t.shape))
    assert math.prod(logical) == t.n_elements, (t.name, logical, t.n_elements)

Type guard

def has_consistent_shape(t, field) -> bool:
    logical = tuple(int(d) for d in field.contents()) if field is not None else tuple(reversed(t.shape))
    return math.prod(logical) == t.n_elements

Try / catch

try:
    meta = read_gguf_tensor_meta(reader, t)
except ValueError as e:
    if 'elements instead of' in str(e):
        raise CheckpointCorruptionError(t.name) from e
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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).

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/d06535d587d32f3a. Report an issue: GitHub.