sgl-project/sglang · critical · ValueError

expert-pack data offset is invalid

Error message

expert-pack data offset is invalid

What it means

The header's data_start offset either leaves the file before the header+index ends (data_start < HEADER_STRUCT.size + index_count*ENTRY_STRUCT.size), or is not aligned to the declared alignment. The reader needs a valid, aligned data region offset to mmap/read expert blobs correctly.

Source

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

            alignment=values[7],
            num_layers=values[8],
            num_experts=values[9],
            top_k=values[10],
            role_count=values[11],
            model_identity_sha256=values[12].hex(),
            source_blob_sha256=values[13].hex(),
            config_sha256=values[14].hex(),
        )
        expected = header.num_layers * header.num_experts * len(ROLE_NAMES)
        if header.index_count != expected or header.role_count != len(ROLE_NAMES):
            raise ValueError("expert-pack header coverage is inconsistent")
        if header.flags & REQUIRED_FLAGS != REQUIRED_FLAGS:
            raise ValueError("expert-pack is not identity triplet layout")
        if header.alignment <= 0 or header.alignment & (header.alignment - 1):
            raise ValueError("expert-pack alignment is invalid")
        minimum = HEADER_STRUCT.size + header.index_count * ENTRY_STRUCT.size
        if header.data_start < minimum or header.data_start % header.alignment:
            raise ValueError("expert-pack data offset is invalid")
        return header


@dataclass(frozen=True)
class ExpertPackEntry:
    layer: int
    expert: int
    role_id: int
    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

View on GitHub (pinned to 0132848349)

Solutions

  1. Regenerate the pack so data_start = align_up(header_size + index_size, alignment)
  2. Keep alignment and layout config unchanged between packing and loading
  3. Verify the file's sha256 against the manifest to rule out corruption

Example fix

# before
data_start = HEADER_STRUCT.size + index_count * ENTRY_STRUCT.size  # unaligned

# after
end_of_index = HEADER_STRUCT.size + index_count * ENTRY_STRUCT.size
data_start = (end_of_index + alignment - 1) & ~(alignment - 1)
Defensive patterns

Strategy: validation

Validate before calling

def data_start_is_valid(path):
    with open(path, "rb") as f:
        v = HEADER_STRUCT.unpack(f.read(HEADER_STRUCT.size))
    data_start, alignment, index_count = v[6], v[7], v[5]
    minimum = HEADER_STRUCT.size + index_count * ENTRY_STRUCT.size
    return data_start >= minimum and data_start % alignment == 0

Prevention

When it happens

Trigger: ExpertPackHeader.read when data_start overlaps the index region or data_start % alignment != 0 — e.g. the packer forgot padding between index and data, or the header was edited to change alignment after writing.

Common situations: Packer bugs that skip alignment padding after the entry index; mixing an old header with a rewritten body; file corruption; changing alignment in config without re-packing.

Related errors

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