sgl-project/sglang · critical · ValueError

expert-pack alignment is invalid

Error message

expert-pack alignment is invalid

What it means

The header's alignment field is not a positive power of two. The reader requires power-of-two alignment to compute data_start % alignment checks and to do aligned (possibly O_DIRECT) reads; zero, negative, or non-power-of-two values indicate header corruption or a bad packer.

Source

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

            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
    pack_offset: int
    pack_nbytes: int

View on GitHub (pinned to 0132848349)

Solutions

  1. Re-download or regenerate the pack and verify its sha256 against the manifest
  2. Rebuild with an explicit power-of-two alignment (256 or 4096)
  3. If producing packs yourself, assert alignment is a power of two before writing the header

Example fix

# before
header.alignment = 384  # writer bug

# after
header.alignment = 256  # power of two, satisfies alignment & (alignment-1) == 0
Defensive patterns

Strategy: validation

Validate before calling

def alignment_is_valid(path):
    with open(path, "rb") as f:
        v = HEADER_STRUCT.unpack(f.read(HEADER_STRUCT.size))
    a = v[7]
    return a > 0 and (a & (a - 1)) == 0

Prevention

When it happens

Trigger: ExpertPackHeader.read when alignment is 0, or a value like 12/24/1000 where alignment & (alignment-1) != 0 — typically from corrupted bytes or a hand-crafted header.

Common situations: Bit-flip corruption of the pack file, incomplete uploads, or packs written by experimental tooling that used arbitrary alignment (e.g. 384) instead of 256/4096.

Related errors

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