sgl-project/sglang · critical · ValueError

expert-pack index is truncated

Error message

expert-pack index is truncated

What it means

While reading an index entry, fewer than ENTRY_STRUCT.size bytes were available — the entry index region is truncated relative to index_count declared in the header. This means the file is shorter than the header claims (corruption or incomplete write/transfer).

Source

Thrown at python/sglang/srt/layers/moe/expert_pack.py:126

    dtype_id: int
    dtype: str
    tensor_name: str
    source_slice_offset: int
    source_slice_nbytes: int
    pack_offset: int
    pack_nbytes: int
    checksum: str
    shape: tuple[int, ...]
    quant_scheme: str
    transform_id: str
    block_size: int
    generation: int

    @classmethod
    def read(cls, stream) -> ExpertPackEntry:
        raw = stream.read(ENTRY_STRUCT.size)
        if len(raw) != ENTRY_STRUCT.size:
            raise ValueError("expert-pack index is truncated")
        values = ENTRY_STRUCT.unpack(raw)
        role_id, rank = values[2], values[3]
        if role_id >= len(ROLE_NAMES) or not 1 <= rank <= 4:
            raise ValueError("expert-pack index role or rank is invalid")
        return cls(
            layer=values[0],
            expert=values[1],
            role_id=role_id,
            dtype_id=values[4],
            dtype=_fixed_string(values[5]),
            tensor_name=_fixed_string(values[6]),
            source_slice_offset=values[9],
            source_slice_nbytes=values[10],
            pack_offset=values[11],
            pack_nbytes=values[12],
            checksum=values[15].hex(),
            shape=tuple(values[16 : 16 + rank]),
            quant_scheme=_fixed_string(values[20]),

View on GitHub (pinned to 0132848349)

Solutions

  1. Verify and re-download/regenerate the pack (compare file size and sha256 with the manifest)
  2. If packing yourself, ensure entries and data are fully flushed/fsynced before writing the header or finalizing the manifest
  3. Check for disk-full or interrupted-write conditions on the machine that produced the pack
Defensive patterns

Strategy: validation

Validate before calling

import os

def pack_looks_complete(path, manifest_path):
    with open(manifest_path) as f:
        m = json.load(f)
    if not m.get("complete"):
        return False
    expected = m.get("file_size") or m.get("pack_bytes")
    return expected is None or os.path.getsize(path) == expected

Prevention

When it happens

Trigger: ExpertPackEntry.read returning a short read because the file ends before index_count entries were consumed — e.g. an interrupted pack write, a truncated download, or a header with an inflated index_count.

Common situations: Killed packing job that wrote the header but not all entries; partial file transfer; disk-full during export; concatenated/appended files with wrong length.

Related errors

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