{"record":{"id":"d327d0885aff6402","repo":"headroomlabs-ai/headroom","slug":"model-id-model-safetensors-state-dict-mismatch","errorCode":null,"errorMessage":"{model_id} model.safetensors: state_dict mismatch against HeadroomCompressorModel (missing={list(missing)[:5]}, unexpected={list(unexpected)[:5]}). Refusing to run with unloaded weights.","messagePattern":"(.+?) model\\.safetensors: state_dict mismatch against HeadroomCompressorModel \\(missing=(.+?), unexpected=(.+?)\\)\\. Refusing to run with unloaded weights\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"headroom/transforms/kompress_compressor.py","lineNumber":817,"sourceCode":"        (\"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        )\n\n\ndef _load_pytorch_weights(model: Any, model_id: str, *, allow_download: bool) -> None:\n    \"\"\"Load PyTorch weights into ``model``, preferring the merged v2 checkpoint.\n\n    ``merged.pt`` (when the repo ships one) holds LoRA-merged sub-state-dicts\n    keyed by submodule name. In a PEFT-trained repo, ``model.safetensors`` is\n    the *unmerged* adapter checkpoint (encoder keys prefixed\n    ``encoder.base_model.model...``) and does not map onto this module tree at\n    all, so it is only used as a fallback for repos that never shipped a\n    merged checkpoint (e.g. the original non-LoRA kompress-base).\n\n    In cache-only mode (``allow_download=False``) a ``merged.pt`` cache miss is\n    ambiguous: it could mean the repo has no merged checkpoint (safe to use the","sourceCodeStart":799,"sourceCodeEnd":835,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/kompress_compressor.py#L799-L835","documentation":"Raised by _load_plain_state_dict (the pre-v2 / non-PEFT fallback path) when loading model.safetensors into the full HeadroomCompressorModel with strict=False still leaves missing or unexpected keys. Unlike the merged.pt path, this is the final weights source, so the loader refuses to run a model with partially unloaded weights rather than emitting garbage compressions — the message says exactly that ('Refusing to run with unloaded weights').","triggerScenarios":"A repo without merged.pt falls back to model.safetensors, and that safetensors file was exported against a different HeadroomCompressorModel architecture (key names/shapes drifted), so strict=False still reports mismatches.","commonSituations":"Loading a PEFT-format repo's unmerged adapter safetensors through the plain path; architecture refactor in headroom outdating an old safetensors artifact; fork repos with renamed modules.","solutions":["Use a model_id whose model.safetensors matches your headroom version (check the repo's export script version).","If the repo is PEFT-format, ensure a merged.pt exists (or merge and upload one) so the v2 path is used instead of the plain path.","Clear the local cache and re-download in case of a corrupted/stale artifact before assuming architecture mismatch."],"exampleFix":"# before: adapter-format model.safetensors routed to plain loader -> RuntimeError\n# after: export a merged v2 checkpoint so the correct loader is used\n# python scripts/export_kompress_v2_onnx.py --model <model_id> --emit-merged-pt\n# then reload: load_kompress_model('<model_id>')","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    load_kompress_model(model_id)\nexcept RuntimeError as e:\n    if \"Refusing to run with unloaded weights\" in str(e):\n        disable_kompress_and_use_builtin_compressors()\n    else:\n        raise","preventionTips":["Never load a PEFT/adapter-format model.safetensors via the plain path — ship a merged.pt.","Export checkpoints with the current export script (scripts/export_kompress_v2_onnx.py).","Treat this error as hard-stop: partially loaded weights yield silent garbage, so do not catch-and-continue into compression."],"tags":["safetensors","state-dict","model-loading","architecture-mismatch"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}