{"record":{"id":"a85d5245c572fd5e","repo":"headroomlabs-ai/headroom","slug":"model-id-section-state-dict-mismatch-against","errorCode":null,"errorMessage":"{model_id} {section}: state_dict mismatch against {type(submodule).__name__} (missing={list(missing)[:5]}, unexpected={list(unexpected)[:5]}). The checkpoint no longer matches HeadroomCompressorModel's architecture.","messagePattern":"(.+?) (.+?): state_dict mismatch against (.+?) \\(missing=(.+?), unexpected=(.+?)\\)\\. The checkpoint no longer matches HeadroomCompressorModel's architecture\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"headroom/transforms/kompress_compressor.py","lineNumber":803,"sourceCode":"    \"\"\"\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\ndef _load_plain_state_dict(model: Any, weights_path: str, model_id: str) -> None:\n    \"\"\"Load a plain, already-merged full state-dict (the pre-v2 / non-PEFT format).\"\"\"\n    from safetensors.torch import load_file\n\n    state_dict = load_file(weights_path)\n    missing, unexpected = model.load_state_dict(state_dict, strict=False)\n    if missing or unexpected:\n        raise RuntimeError(\n            f\"{model_id} model.safetensors: state_dict mismatch against \"\n            f\"HeadroomCompressorModel (missing={list(missing)[:5]}, \"\n            f\"unexpected={list(unexpected)[:5]}). Refusing to run with unloaded weights.\"\n        )","sourceCodeStart":785,"sourceCodeEnd":821,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/kompress_compressor.py#L785-L821","documentation":"Raised by _load_merged_state_dict when submodule.load_state_dict(..., strict=False) reports missing or unexpected keys for one of the three sections — the checkpoint's tensor names no longer line up with HeadroomCompressorModel's submodules (encoder/token_head/span_conv). It surfaces at most 5 keys each way and states plainly that the checkpoint no longer matches the model architecture, typically after a code-side architecture change versus an older checkpoint.","triggerScenarios":"Loading merged.pt exported against an older (or newer) HeadroomCompressorModel definition — e.g. package upgraded but HF cache still holds the pre-upgrade checkpoint, or vice versa.","commonSituations":"Version skew between the headroom package and the downloaded model repo; a fork fine-tuned from a different base exporting mismatched key names (LoRA prefixes, renamed modules).","solutions":["Pin the headroom version that matches the model repo's export, or update the model repo/checkpoint to the current architecture.","Clear the HF cache for that model_id and re-download so checkpoint and code revisions align.","Inspect the listed missing/unexpected keys (LoRA prefix drift is the classic cause) and re-export merged.pt with matching names."],"exampleFix":"# before: package upgraded, cached merged.pt from old arch -> RuntimeError mismatch\n# shell fix:\nrm -rf \"$HF_HOME/hub/models--<org>--<kompress-model>\"\npython -c \"from headroom.transforms.kompress_compressor import load_kompress_model; load_kompress_model('<model_id>')\"","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    _load_pytorch_weights(model, model_id, allow_download=allow_download)\nexcept RuntimeError as e:\n    if \"state_dict mismatch\" in str(e):\n        logger.error(\"checkpoint/model skew for %s; pin versions\", model_id)\n        raise ModelVersionSkew(model_id) from e\n    raise","preventionTips":["Keep headroom package version and model-repo revision in lockstep.","Clear the HF cache for the model after upgrading headroom.","Watch for LoRA key-prefix drift when using forked/fine-tuned checkpoints."],"tags":["pytorch","state-dict","version-skew","model-loading"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}