{"record":{"id":"248aff6cd4b80ee4","repo":"sgl-project/sglang","slug":"f-adapter-weights-at-component-weights-path-do","errorCode":null,"errorMessage":"f\"Adapter weights at '{component_weights_path}' do not match the instantiated {cls_name}. Missing: {sorted(missing)}. Unexpected: {sorted(unexpected)}. This usually means the adapter config or its weight-name mapping is wrong.\"","messagePattern":"f\"Adapter weights at '(.+?)' do not match the instantiated (.+?)\\. Missing: (.+?)\\. Unexpected: (.+?)\\. This usually means the adapter config or its weight-name mapping is wrong\\.\"","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/loader/component_loaders/adapter_loader.py","lineNumber":89,"sourceCode":"            server_args, component_name, precision_attr=\"dit_precision\"\n        )\n\n        config_cls = self._CONFIG_CLASSES[component_name]\n        with set_default_torch_dtype(default_dtype), skip_init_modules():\n            adapter_cfg = config_cls()\n            adapter_cfg.update_model_arch(config)\n            model = model_cls(adapter_cfg).to(device=target_device, dtype=default_dtype)\n\n        loaded = load_safetensors_state_dict(component_weights_path)\n        mapping = adapter_cfg.arch_config.param_names_mapping\n        loaded = {_remap_connector_key(k, mapping): v for k, v in loaded.items()}\n\n        missing, unexpected = model.load_state_dict(loaded, strict=False)\n        # `strict=False` because a checkpoint carries either the shared\n        # `text_proj_in` or the per-modality projections, never both. Anything\n        # else uninitialized would surface later as garbage embeddings.\n        if missing or unexpected:\n            raise ValueError(\n                f\"Adapter weights at '{component_weights_path}' do not match the \"\n                f\"instantiated {cls_name}. Missing: {sorted(missing)}. \"\n                f\"Unexpected: {sorted(unexpected)}. This usually means the \"\n                \"adapter config or its weight-name mapping is wrong.\"\n            )\n\n        return model\n\n\ndef _remap_connector_key(key: str, param_names_mapping: dict[str, str]) -> str:\n    for pattern, replacement in param_names_mapping.items():\n        key, replaced = re.subn(pattern, replacement, key)\n        if replaced:\n            break\n    return key\n","sourceCodeStart":71,"sourceCodeEnd":105,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/loader/component_loaders/adapter_loader.py#L71-L105","documentation":"After loading the adapter state dict with strict=False, the loader checks missing and unexpected keys. A checkpoint that carries neither the shared text_proj_in nor the per-modality projections — or has extra/foreign keys — produces this ValueError, indicating the adapter config or weight-name mapping is wrong.","triggerScenarios":"Loading an adapter checkpoint whose keys don't line up with the instantiated class: keys missing entirely (missing non-projection weights) or extra keys not in the model (unexpected), e.g. a checkpoint from a different adapter class or version.","commonSituations":"Adapter checkpoint from a different adapter architecture than the config's _class_name indicates; weight-name remapping bug in the loader for a new adapter variant; mixing checkpoints from different revisions of the same model family.","solutions":["Verify config.json's _class_name matches the checkpoint's actual architecture (re-download the matching adapter)","Regenerate/re-download the adapter weights so they match the instantiated class","If developing a new adapter variant, extend the weight-name mapping so checkpoint keys are translated to model keys"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import json, torch\n\nexpected = set(model.state_dict())\nckpt_keys = set(torch.load(weights_file, map_location='cpu').keys())\n# only projection weights may legitimately differ\nnon_proj = expected.symmetric_difference(ckpt_keys) - {'text_proj_in.weight', 'text_proj_in.bias'}\nassert not non_proj, f\"key mismatch: {non_proj}\"","typeGuard":null,"tryCatchPattern":"try:\n    loader.load_customized(path, server_args, name)\nexcept ValueError as e:\n    if \"do not match\" in str(e):\n        # checkpoint/config architecture mismatch: fetch matching revision\n        download_matching_revision(path, revision)\n    raise","preventionTips":["Pin the adapter revision matching the base model","Verify _class_name matches the checkpoint provenance before loading"],"tags":["model-loading","state-dict","adapter","weight-mismatch"],"backgroundTag":"state-dict-key-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}