What causes "expert-pack index role or rank is invalid" in sgl-project/sglang?

Rebuild the pack with the same sglang version that will read it, so ENTRY_STRUCT layouts match

sgl-project/sglang · critical · ValueError

expert-pack index role or rank is invalid

Error message

expert-pack index role or rank is invalid

What it means

An index entry's role_id is >= 3 (outside gate/up/down) or its rank field is outside 1..4. The per-entry rank is validated to the 1–4 range and roles to the three known names, so out-of-range values mean a malformed or incompatible entry encoding.

Source

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

    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]),
            transform_id=_fixed_string(values[21]),
            block_size=values[22],
            generation=values[23],
        )

View on GitHub (pinned to 0132848349)

Solutions

Rebuild the pack with the same sglang version that will read it, so ENTRY_STRUCT layouts match
Verify the reader and packer come from the same sglang release (struct sizes are also cross-checked earlier in the header)
Validate the file checksum against the manifest to rule out corruption

Defensive patterns

Strategy: validation

Validate before calling

def entry_ranges_ok(role_id, rank):
    return 0 <= role_id < 3 and 1 <= rank <= 4

Prevention

Use the same sglang version for packing and serving so ENTRY_STRUCT layouts match
Treat any entry-level validation failure as corruption and re-verify the sha256

When it happens

Trigger: ExpertPackEntry.read when values[2] (role_id) >= len(ROLE_NAMES) or values[3] (rank) is 0 or > 4 — e.g. a pack written with more roles or a different entry struct layout (struct-size skew between writer and reader).

Common situations: Version mismatch where the writer's ENTRY_STRUCT differs from the reader's; experimental packs with extra roles (e.g. shared experts); corrupted entry bytes.

Related errors

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