{"record":{"id":"13f94141a457acd7","repo":"headroomlabs-ai/headroom","slug":"merged-pt-for-model-id-is-missing-missing-secti","errorCode":null,"errorMessage":"merged.pt for {model_id} is missing {missing_sections}; found keys: {sorted(ckpt)}. This checkpoint format is not what the loader expects.","messagePattern":"merged\\.pt for (.+?) is missing (.+?); found keys: (.+?)\\. This checkpoint format is not what the loader expects\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"headroom/transforms/kompress_compressor.py","lineNumber":791,"sourceCode":"# scripts/export_kompress_v2_onnx.py, which this mirrors).\n_MERGED_CHECKPOINT_KEYS = (\"encoder_state_dict\", \"token_head_state_dict\", \"span_conv_state_dict\")\n\n\ndef _load_merged_state_dict(model: Any, ckpt_path: str, model_id: str) -> None:\n    \"\"\"Load a merged v2-style checkpoint (LoRA already folded into the encoder).\n\n    The checkpoint is a dict of per-submodule state-dicts\n    (``encoder_state_dict`` / ``token_head_state_dict`` / ``span_conv_state_dict``)\n    rather than a single flat state-dict, so each piece is loaded into its\n    matching submodule directly instead of via a single ``load_state_dict``\n    call on the whole model.\n    \"\"\"\n    import torch\n\n    ckpt = torch.load(ckpt_path, map_location=\"cpu\")\n    missing_sections = [k for k in _MERGED_CHECKPOINT_KEYS if k not in ckpt]\n    if missing_sections:\n        raise RuntimeError(\n            f\"merged.pt for {model_id} is missing {missing_sections}; found keys: \"\n            f\"{sorted(ckpt)}. This checkpoint format is not what the loader expects.\"\n        )\n\n    for section, submodule in (\n        (\"encoder_state_dict\", model.encoder),\n        (\"token_head_state_dict\", model.token_head),\n        (\"span_conv_state_dict\", model.span_conv),\n    ):\n        missing, unexpected = submodule.load_state_dict(ckpt[section], strict=False)\n        if missing or unexpected:\n            raise RuntimeError(\n                f\"{model_id} {section}: state_dict mismatch against {type(submodule).__name__} \"\n                f\"(missing={list(missing)[:5]}, unexpected={list(unexpected)[:5]}). \"\n                \"The checkpoint no longer matches HeadroomCompressorModel's architecture.\"\n            )\n\n","sourceCodeStart":773,"sourceCodeEnd":809,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/kompress_compressor.py#L773-L809","documentation":"Raised by _load_merged_state_dict when the downloaded merged.pt checkpoint lacks one or more of the three expected sub-state-dict sections (encoder_state_dict, token_head_state_dict, span_conv_state_dict). The v2 loader expects a dict-of-state-dicts keyed by submodule (see scripts/export_kompress_v2_onnx.py), not a flat tensor dict; the error enumerates what is missing and what keys were actually found so you can tell a wrong-format or stale file at a glance.","triggerScenarios":"Loading a Kompress model whose cached merged.pt is from an older export format, was replaced by a flat checkpoint, or is truncated/corrupt — i.e. torch.load succeeds but the top-level keys don't include all three sections.","commonSituations":"HF repo revision changed the checkpoint layout; a stale local cache from a previous model version; someone pointed model_id at a fork whose merged.pt is the pre-v2 format.","solutions":["Clear the cached merged.pt (huggingface-cli delete ... or remove it under HF_HOME) and re-download the current revision.","Compare 'found keys' in the message against the expected three sections to identify the format mismatch.","If the repo genuinely ships no v2 merged checkpoint, use a model_id that does, or rely on the plain model.safetensors fallback path."],"exampleFix":"# before: stale/corrupt merged.pt in cache -> RuntimeError on missing sections\n# shell fix:\nhuggingface-cli delete <model_id> merged.pt\npython -c \"from headroom.transforms.kompress_compressor import load_kompress_model; load_kompress_model('<model_id>')\"","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    _load_merged_state_dict(model, ckpt_path, model_id)\nexcept RuntimeError as e:\n    if \"merged.pt\" in str(e) and \"missing\" in str(e):\n        evict_hf_file(model_id, \"merged.pt\")  # then retry once with a fresh download\n        _load_merged_state_dict(model, re_download(model_id, \"merged.pt\"), model_id)\n    else:\n        raise","preventionTips":["Evict and re-download checkpoints after headroom upgrades instead of trusting stale caches.","Pin model repos to a known-good revision.","Check the 'found keys' list in the message before assuming corruption."],"tags":["pytorch","checkpoint","model-loading","cache"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}