sgl-project/sglang · critical · ValueError

expert-pack is not identity triplet layout

Error message

expert-pack is not identity triplet layout

What it means

The header's flags bitmask does not contain REQUIRED_FLAGS (bits 0 and 1), meaning the pack is not stored in the identity triplet layout the runtime requires (one entry per gate/up/down role per expert, with identity transform). The reader refuses packs produced with non-trivial transforms or a different layout.

Source

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

            raise ValueError("expert-pack struct sizes do not match")
        header = cls(
            flags=values[4],
            index_count=values[5],
            data_start=values[6],
            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

View on GitHub (pinned to 0132848349)

Solutions

  1. Re-pack the experts with the current tool, which sets REQUIRED_FLAGS (bits 0|1) for identity triplet layout
  2. Check the packer version used to create the file and upgrade/rebuild so flags match the reader
  3. If you need transformed layouts, use a reader/runtime version that supports those flags instead

Example fix

# before
# pack created with transform-mode tooling -> flags=0
store = ExpertPackStore("experts.pack")

# after
# rebuild with identity triplet layout (sets flags bits 0 and 1)
store = ExpertPackStore("experts.identity.pack")
Defensive patterns

Strategy: validation

Validate before calling

def has_identity_triplet_flags(path):
    with open(path, "rb") as f:
        v = HEADER_STRUCT.unpack(f.read(HEADER_STRUCT.size))
    return v[4] & 0b11 == 0b11

Prevention

When it happens

Trigger: ExpertPackHeader.read on a pack whose flags field is missing bit 0 or bit 1 — e.g. produced by a packer that applied transforms (transposed/quantized-repacked layout) or a legacy/partial pack written before the flags existed.

Common situations: Packs produced by an older or third-party packing tool that did not set the identity-triplet flags; attempting to load a transform-based (non-identity) pack into a runtime that only supports identity layout; version skew between packer and reader.

Related errors

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