{"record":{"id":"bda2344025517cf1","repo":"sgl-project/sglang","slug":"expert-pack-header-coverage-is-inconsistent","errorCode":null,"errorMessage":"expert-pack header coverage is inconsistent","messagePattern":"expert-pack header coverage is inconsistent","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/layers/moe/expert_pack.py","lineNumber":92,"sourceCode":"            raise ValueError(\"expert-pack magic or version does not match\")\n        if values[2] != HEADER_STRUCT.size or values[3] != ENTRY_STRUCT.size:\n            raise ValueError(\"expert-pack struct sizes do not match\")\n        header = cls(\n            flags=values[4],\n            index_count=values[5],\n            data_start=values[6],\n            alignment=values[7],\n            num_layers=values[8],\n            num_experts=values[9],\n            top_k=values[10],\n            role_count=values[11],\n            model_identity_sha256=values[12].hex(),\n            source_blob_sha256=values[13].hex(),\n            config_sha256=values[14].hex(),\n        )\n        expected = header.num_layers * header.num_experts * len(ROLE_NAMES)\n        if header.index_count != expected or header.role_count != len(ROLE_NAMES):\n            raise ValueError(\"expert-pack header coverage is inconsistent\")\n        if header.flags & REQUIRED_FLAGS != REQUIRED_FLAGS:\n            raise ValueError(\"expert-pack is not identity triplet layout\")\n        if header.alignment <= 0 or header.alignment & (header.alignment - 1):\n            raise ValueError(\"expert-pack alignment is invalid\")\n        minimum = HEADER_STRUCT.size + header.index_count * ENTRY_STRUCT.size\n        if header.data_start < minimum or header.data_start % header.alignment:\n            raise ValueError(\"expert-pack data offset is invalid\")\n        return header\n\n\n@dataclass(frozen=True)\nclass ExpertPackEntry:\n    layer: int\n    expert: int\n    role_id: int\n    dtype_id: int\n    dtype: str\n    tensor_name: str","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/layers/moe/expert_pack.py#L74-L110","documentation":"The expert-pack binary header declares an index_count that does not equal num_layers * num_experts * 3 (ROLE_NAMES = gate/up/down), or role_count != 3. The reader (SGLANG-EXPERTPACK-v1) enforces that every (layer, expert, role) triplet has exactly one index entry, so any mismatch means the pack was built for a different topology or is corrupt.","triggerScenarios":"ExpertPackHeader.read(stream) on a pack whose header fields num_layers/num_experts/index_count/role_count disagree — e.g. a pack exported for a different model (num_experts 256 vs 8), a hand-edited header, or a truncated/rewritten file where role_count is not 3.","commonSituations":"Using an expert-pack built for a different MoE model or model revision; mixing packs from older/newer versions of the packer tool; partially transferred or corrupted pack files.","solutions":["Regenerate the expert-pack so it matches the model's num_layers/num_experts and packs all three roles (gate, up, down)","Verify the pack was produced by the matching version of the packing tool and fully transferred (compare sha256 with the manifest)","If num_experts or num_layers of your model changed (e.g. different quant/config), rebuild the pack from the new checkpoint"],"exampleFix":"# before\nstore = ExpertPackStore(\"mymodel.expertpack\", manifest_path=None)  # built for 8-expert model\n\n# after\nstore = ExpertPackStore(\"mymodel.k8.expertpack\")  # pack regenerated with matching num_layers/num_experts and role_count=3","handlingStrategy":"validation","validationCode":"import struct\nfrom sglang.srt.layers.moe.expert_pack import HEADER_STRUCT, ROLE_NAMES, MAGIC\n\ndef header_covers_topology(path, num_layers, num_experts):\n    with open(path, \"rb\") as f:\n        raw = f.read(HEADER_STRUCT.size)\n    v = HEADER_STRUCT.unpack(raw)\n    idx_count, n_layers, n_experts, role_count = v[5], v[8], v[9], v[11]\n    return (idx_count == n_layers * n_experts * len(ROLE_NAMES)\n            and role_count == len(ROLE_NAMES)\n            and n_layers == num_layers and n_experts == num_experts)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a naming convention that encodes num_layers/num_experts in the pack filename","Always validate the pack against the model config (num_experts, num_hidden_layers) before constructing the store"],"tags":["moe","expert-pack","binary-format","header-validation","sglang"],"backgroundTag":"file-format-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}